The Open Framework for Building Agents
fix: trace framework actions consistently (#4392)
Chad Hietaladd902e294f89
diff --git a/.changeset/framework-action-tracing.md b/.changeset/framework-action-tracing.mdnew file mode 100644index 000000000..afae44c6c--- /dev/null+++ b/.changeset/framework-action-tracing.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Mark eve-provided tools on tool execution spans, and emit tool execution spans for task controls and deferred workflow calls. Local and remote agent tool calls retain their dispatch kind, including background tasks.diff --git a/e2e/fixtures/agent-prompt-cache/evals/parallel-review.eval.ts b/e2e/fixtures/agent-prompt-cache/evals/parallel-review.eval.tsindex d37264aa5..f916bae62 100644--- a/e2e/fixtures/agent-prompt-cache/evals/parallel-review.eval.ts+++ b/e2e/fixtures/agent-prompt-cache/evals/parallel-review.eval.ts@@ -47,7 +47,7 @@ function expectFiveReviewers(started: EveEvalTurn) {.filter((event) => event.type === "actions.requested").flatMap(({ data }) =>data.actions- .filter((action) => action.kind === "tool-call" && action.toolName === "reviewer")+ .filter((action) => action.kind === "subagent-call" && action.subagentName === "reviewer").map(() => `${data.turnId}:${data.stepIndex}`),);assert.equal(launchSteps.length, 5, "five reviewer requests");diff --git a/e2e/fixtures/agent-subagents/evals/local-delegation.eval.ts b/e2e/fixtures/agent-subagents/evals/local-delegation.eval.tsindex 0d84702be..fbf208215 100644--- a/e2e/fixtures/agent-subagents/evals/local-delegation.eval.ts+++ b/e2e/fixtures/agent-subagents/evals/local-delegation.eval.ts@@ -16,6 +16,15 @@ export default defineEval({);completed.expectOk();completed.messageIncludes(SUBAGENT_TOKEN);+ completed.eventsSatisfy("local agent calls preserve dispatch kind", (events) =>+ events.some(+ (event) =>+ event.type === "actions.requested" &&+ event.data.actions.some(+ (action) => action.kind === "subagent-call" && action.name === "echo-marker",+ ),+ ),+ );t.succeeded();t.calledSubagent("echo-marker", { status: "completed" });diff --git a/e2e/fixtures/agent-subagents/evals/remote-subagent-stream.eval.ts b/e2e/fixtures/agent-subagents/evals/remote-subagent-stream.eval.tsindex 6e6494a19..60c553aae 100644--- a/e2e/fixtures/agent-subagents/evals/remote-subagent-stream.eval.ts+++ b/e2e/fixtures/agent-subagents/evals/remote-subagent-stream.eval.ts@@ -22,6 +22,15 @@ export default defineEval({async test(t) {const turn = await t.send(CREATE_CHILD_MESSAGE);turn.expectOk();+ turn.eventsSatisfy("remote agent calls preserve dispatch kind", (events) =>+ events.some(+ (event) =>+ event.type === "actions.requested" &&+ event.data.actions.some(+ (action) => action.kind === "remote-agent-call" && action.name === "remote-loopback",+ ),+ ),+ );const started = await requireRemoteSession(t, turn);const childEvents: MessageStreamEvent[] = [];diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.tsindex c83912e1e..ec687083e 100644--- a/packages/eve/src/context/build-dynamic-tools.ts+++ b/packages/eve/src/context/build-dynamic-tools.ts@@ -141,6 +141,7 @@ export function replayDynamicTools(-readonly [K in keyof HarnessToolDefinition]: HarnessToolDefinition[K];} = {availableInSubagents: entry.availableInSubagents,+ frameworkTool: entry.frameworkTool,description: entry.description,endsTurn: entry.endsTurn,execute: createToolExecuteWithAuth({diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.tsindex e645e8d3f..4373a4a86 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts@@ -1,4 +1,5 @@import type { ModelMessage } from "ai";+import { isFrameworkTool } from "#tools/provided/framework-tool.js";import { isWorkflowToolDefinition } from "#tools/workflow-definition.js";@@ -323,6 +324,7 @@ function createMetadata(input: {name: input.name,}),description: input.entry.description,+ frameworkTool: isFrameworkTool(input.entry) || undefined,endsTurn: readDynamicEndsTurn(input.name, input.entry.endsTurn) || undefined,entryKey: input.entryKey,inputSchema: serializeInputSchema(input.entry.inputSchema),diff --git a/packages/eve/src/context/dynamic-tool-metadata.ts b/packages/eve/src/context/dynamic-tool-metadata.tsindex 8087c8be5..6014a14aa 100644--- a/packages/eve/src/context/dynamic-tool-metadata.ts+++ b/packages/eve/src/context/dynamic-tool-metadata.ts@@ -2,6 +2,7 @@ import type { JsonObject } from "#shared/json.js";import type { DurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";interface DynamicToolMetadataBase {+ readonly frameworkTool?: boolean;readonly availableInSubagents?: boolean;readonly name: string;readonly description: string;diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.tsindex 8637530e7..4d48222cb 100644--- a/packages/eve/src/execution/node-step.ts+++ b/packages/eve/src/execution/node-step.ts@@ -1,11 +1,11 @@import type { LanguageModel } from "ai";+import { isFrameworkTool } from "#tools/provided/framework-tool.js";import type { Runtime, SessionCapabilities } from "#channel/types.js";import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";import { preparePersistedStepDynamicToolMetadata } from "#context/dynamic-tool-lifecycle.js";import type { HarnessToolDefinition } from "#harness/execute-tool.js";import type { ExecutionInstrumentation } from "#instrumentation/runtime.js";-import { LOAD_SKILL_TOOL_NAME } from "#runtime/skills/fragment-context.js";import { createToolLoopHarness } from "#harness/tool-loop.js";import type { HandleEventFn, HarnessToolMap, StepFn } from "#harness/types.js";import { resolveInstalledPackageInfo } from "#internal/application/package.js";@@ -268,10 +268,8 @@ function createRegisteredHarnessToolDefinition(input: {rawExecute,scope: def.name,}),- frameworkAction:- def.owner.kind === "framework" && def.name === LOAD_SKILL_TOOL_NAME- ? "load-skill"- : undefined,+ frameworkTool: isFrameworkTool(def) || def.owner.kind === "framework",+ frameworkAction: def.behavior?.presentation === "load-skill" ? "load-skill" : undefined,inputSchema: def.inputSchema ?? UNSPECIFIED_INPUT_SCHEMA,name: def.name,approval: def.approval,diff --git a/packages/eve/src/execution/session/task-tool-tracing-step.ts b/packages/eve/src/execution/session/task-tool-tracing-step.tsnew file mode 100644index 000000000..0527e830b--- /dev/null+++ b/packages/eve/src/execution/session/task-tool-tracing-step.ts@@ -0,0 +1,42 @@+import {+ publishFromSessionStep,+ restoreSessionStep,+ type SessionStepState,+} from "#execution/publish-session-events.js";+import { withSessionStateDelta } from "#execution/session/state-delta.js";+import {+ bindSessionInstrumentation,+ type ExecutionInstrumentation,+} from "#instrumentation/runtime.js";+import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";+import { BundleKey } from "#runtime/sessions/runtime-context-keys.js";++/** The step output preserves the start time when the workflow resumes in another worker. */+export async function startTaskToolCallsStep(): Promise<number> {+ "use step";+ return Date.now();+}++export async function traceTaskToolCallStep(+ target: SessionStepState,+ call: Parameters<ExecutionInstrumentation["instrumentTaskToolCall"]>[0],+) {+ "use step";+ return await withSessionStateDelta(target, async (input) => {+ const restored = await restoreSessionStep(input);+ const { published } = await publishFromSessionStep(restored, {+ origin: "own",+ async publish(_emit, session) {+ const instrumentation = bindSessionInstrumentation({+ ctx: restored.ctx,+ agentName: resolveEffectiveAgentRuntime(restored.ctx.require(BundleKey), restored.ctx)+ .turnAgent.id,+ rootSessionId: session.rootSessionId ?? session.sessionId,+ sessionId: session.sessionId,+ });+ await instrumentation?.instrumentTaskToolCall(call);+ },+ });+ return published;+ });+}diff --git a/packages/eve/src/execution/session/turn.test.ts b/packages/eve/src/execution/session/turn.test.tsindex f9adba77a..d6f3aa7a5 100644--- a/packages/eve/src/execution/session/turn.test.ts+++ b/packages/eve/src/execution/session/turn.test.ts@@ -38,6 +38,7 @@ import type {WorkflowToolRunRef,} from "#execution/tools/workflow/messages.js";import type { TokenUsage } from "#shared/token-usage.js";+import { traceTaskToolCallStep } from "#execution/session/task-tool-tracing-step.js";vi.mock("#compiled/@workflow/core/index.js", async (importOriginal) => ({...(await importOriginal()),@@ -60,12 +61,17 @@ vi.mock("#execution/tools/workflow/interrupt.js", () => ({vi.mock("#execution/session/turn-waiting-step.js", () => ({publishTurnWaitingStep: vi.fn(async () => ({ stateDelta: {} })),}));+vi.mock("#execution/session/task-tool-tracing-step.js", () => ({+ startTaskToolCallsStep: vi.fn(async () => Date.now()),+ traceTaskToolCallStep: vi.fn(async () => ({ stateDelta: {} })),+}));vi.mock("#execution/tools/workflow/emit-workflow-tool-run-report-step.js", () => ({emitAgentStartedStep: vi.fn(),emitWorkflowToolRunReportStep: vi.fn(),}));beforeEach(() => {+ vi.mocked(traceTaskToolCallStep).mockClear();vi.mocked(routeDeliverToChildren).mockReset().mockImplementation(@@ -998,6 +1004,16 @@ describe("SessionExecution checkpoints", () => {// no workflow tool run to stop.expect(dispatchCoordinationStep).not.toHaveBeenCalled();expect(cancelDescendantTurnsStep).not.toHaveBeenCalled();+ expect(traceTaskToolCallStep).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ callId: "wait-call",+ toolName: "task_wait",+ failed: true,+ startedAtMs: expect.any(Number),+ completedAtMs: expect.any(Number),+ }),+ );});it("admits an idle agent task's usage report while the turn waits and counts it", async () => {diff --git a/packages/eve/src/execution/session/turn.ts b/packages/eve/src/execution/session/turn.tsindex b15861022..04d1cdbc9 100644--- a/packages/eve/src/execution/session/turn.ts+++ b/packages/eve/src/execution/session/turn.ts@@ -46,6 +46,10 @@ import {import { resolveRuntimeActionResultsForCallIds } from "#runtime/actions/results.js";import type { RuntimeActionResult } from "#shared/action-types.js";import type { TokenUsage } from "#shared/token-usage.js";+import {+ startTaskToolCallsStep,+ traceTaskToolCallStep,+} from "#execution/session/task-tool-tracing-step.js";/** True when a delegating parent (local or remote) receives this session's input requests. */export function hasDelegatedCallerContext(serializedContext: Record<string, unknown>): boolean {@@ -361,73 +365,76 @@ export class SessionExecution {acceptedAtMsByCallId.set(result.callId, Date.now());};let taskWaits = await this.answerTaskToolCalls(input.taskToolCalls, accept);-- while (true) {- taskWaits = this.resolveTaskWaits(taskWaits, interrupted, accept);- const ready = resolveRuntimeActionResultsForCallIds({- pendingCallIds: input.pendingCallIds,- results,- });- if (ready !== undefined) {- const delegatedUsage = ready.flatMap((result) => {- const usage = delegatedUsageByCallId.get(result.callId);- return usage === undefined ? [] : [usage];+ try {+ while (true) {+ taskWaits = await this.resolveTaskWaits(taskWaits, interrupted, accept);+ const ready = resolveRuntimeActionResultsForCallIds({+ pendingCallIds: input.pendingCallIds,+ results,});- return {- acceptedAtMsByCallId: Object.fromEntries(- ready.map((result) => [result.callId, acceptedAtMsByCallId.get(result.callId)!]),- ),- ...(delegatedUsage.length > 0 && { delegatedUsage }),- results: ready,- };- }+ if (ready !== undefined) {+ const delegatedUsage = ready.flatMap((result) => {+ const usage = delegatedUsageByCallId.get(result.callId);+ return usage === undefined ? [] : [usage];+ });+ return {+ acceptedAtMsByCallId: Object.fromEntries(+ ready.map((result) => [result.callId, acceptedAtMsByCallId.get(result.callId)!]),+ ),+ ...(delegatedUsage.length > 0 && { delegatedUsage }),+ results: ready,+ };+ }- const timers = taskWaits.flatMap((wait) => (wait.timer === undefined ? [] : [wait.timer]));- const next = await input.turn.nextRuntimeEvent(timers);- if (next === "cancelled") return next;- if (next.kind === "timeout") {- for (const wait of taskWaits) {- if (wait.callId === next.callId) wait.timedOut = true;+ const timers = taskWaits.flatMap((wait) => (wait.timer === undefined ? [] : [wait.timer]));+ const next = await input.turn.nextRuntimeEvent(timers);+ if (next === "cancelled") return next;+ if (next.kind === "timeout") {+ for (const wait of taskWaits) {+ if (wait.callId === next.callId) wait.timedOut = true;+ }+ continue;}- continue;- }- if (next.kind === "input") continue;- if (next.kind === "steering") {- // Only the first steering message interrupts; later ones wait for the calls anyway.- if (!interrupted) await this.interruptWaitedWorkflowCalls(input.pendingCallIds, results);- interrupted = true;- continue;- }- if (next.kind === "runtime-action-result") {- const snapshot = this.input.cursor.sessionState.snapshot.session.state;- const accepted = next.results.filter(- (result) =>- result.kind === "tool-result" &&- isInboxToolResultFromRecordedWorkflowToolRun(snapshot, result),- );- if (accepted.length > 0) {- const acceptedAtMs = Date.now();- results.push(...accepted);- for (const result of accepted) acceptedAtMsByCallId.set(result.callId, acceptedAtMs);+ if (next.kind === "input") continue;+ if (next.kind === "steering") {+ // Only the first steering message interrupts; later ones wait for the calls anyway.+ if (!interrupted) await this.interruptWaitedWorkflowCalls(input.pendingCallIds, results);+ interrupted = true;+ continue;+ }+ if (next.kind === "runtime-action-result") {+ const snapshot = this.input.cursor.sessionState.snapshot.session.state;+ const accepted = next.results.filter(+ (result) =>+ result.kind === "tool-result" &&+ isInboxToolResultFromRecordedWorkflowToolRun(snapshot, result),+ );+ if (accepted.length > 0) {+ const acceptedAtMs = Date.now();+ results.push(...accepted);+ for (const result of accepted) acceptedAtMsByCallId.set(result.callId, acceptedAtMs);+ }+ continue;}- continue;- }- const result = await this.handleWorkflowMessage(next.message);- if (result === undefined) continue;- accept(result);- if (next.message.kind === "outcome" && next.message.usage !== undefined) {- delegatedUsageByCallId.set(result.callId, next.message.usage);+ const result = await this.handleWorkflowMessage(next.message);+ if (result === undefined) continue;+ accept(result);+ if (next.message.kind === "outcome" && next.message.usage !== undefined) {+ delegatedUsageByCallId.set(result.callId, next.message.usage);+ }}+ } finally {+ for (const wait of taskWaits) await this.traceTaskWait(wait, undefined, true);}}/** Answers every `task_wait` that can return now; returns the ones still waiting. */- private resolveTaskWaits(+ private async resolveTaskWaits(waits: readonly TaskWait[],interrupted: boolean,accept: (result: RuntimeActionResult) => void,- ): TaskWait[] {+ ): Promise<TaskWait[]> {const table = sessionTaskTable(this.input.cursor);const waiting: TaskWait[] = [];for (const wait of waits) {@@ -440,6 +447,7 @@ export class SessionExecution {continue;}const text = renderTaskWaitResult(result, Date.now() - wait.startedAtMs);+ await this.traceTaskWait(wait, text, interrupted);accept(taskToolResult(wait.callId, TASK_WAIT_TOOL_NAME, text));}return waiting;@@ -457,15 +465,58 @@ export class SessionExecution {accept: (result: RuntimeActionResult) => void,): Promise<TaskWait[]> {const waits: TaskWait[] = [];+ const startedAtMs = calls.length === 0 ? 0 : await startTaskToolCallsStep();for (const call of calls) {- if (call.kind === "task_wait") waits.push(startTaskWait(call));- else accept(await answerTaskCancel(this.input.cursor, call));+ if (call.kind === "task_wait") waits.push(startTaskWait(call, startedAtMs));+ else {+ let result: RuntimeActionResult;+ try {+ result = await answerTaskCancel(this.input.cursor, call);+ } catch (error) {+ await this.input.cursor.advance((state) =>+ traceTaskToolCallStep(state, {+ callId: call.callId,+ toolName: call.kind,+ startedAtMs,+ completedAtMs: Date.now(),+ input: { taskId: call.taskId },+ failed: true,+ }),+ );+ throw error;+ }+ await this.input.cursor.advance((state) =>+ traceTaskToolCallStep(state, {+ callId: call.callId,+ toolName: call.kind,+ startedAtMs,+ completedAtMs: Date.now(),+ input: { taskId: call.taskId },+ output: result.output,+ }),+ );+ accept(result);+ }}- const parked = this.resolveTaskWaits(waits, false, accept);+ const parked = await this.resolveTaskWaits(waits, false, accept);if (parked.length > 0) await this.input.cursor.advance(publishTurnWaitingStep);return parked;}+ private async traceTaskWait(wait: TaskWait, output?: string, failed = false): Promise<void> {+ await this.input.cursor.advance((state) =>+ traceTaskToolCallStep(state, {+ callId: wait.callId,+ toolName: "task_wait",+ startedAtMs: wait.startedAtMs,+ completedAtMs: Date.now(),+ input: wait.input,+ output,+ failed,+ }),+ );+ }+/** Aborts the `abortSignal` of every workflow tool call the wait has no result for yet. */private async interruptWaitedWorkflowCalls(pendingCallIds: readonly string[],@@ -487,6 +538,7 @@ export class SessionExecution {* the turn races against the inbox; nothing polls.*/interface TaskWait {+ readonly input: { readonly timeoutSeconds?: number };readonly callId: string;readonly startedAtMs: number;/** Resolves with the call's id once the timeout passes; absent without a timeout. */@@ -494,10 +546,19 @@ interface TaskWait {timedOut: boolean;}-function startTaskWait(call: Extract<TaskToolCall, { readonly kind: "task_wait" }>): TaskWait {+function startTaskWait(+ call: Extract<TaskToolCall, { readonly kind: "task_wait" }>,+ startedAtMs: number,+): TaskWait {const { callId, timeoutMs } = call;const timer = timeoutMs === undefined ? undefined : sleep(timeoutMs).then(() => callId);- return { callId, startedAtMs: Date.now(), timedOut: false, timer };+ return {+ callId,+ startedAtMs,+ input: timeoutMs === undefined ? {} : { timeoutSeconds: timeoutMs / 1_000 },+ timedOut: timeoutMs === 0,+ timer,+ };}/** An unreadable run registry counts as waiting, so the step runs and logs it. */diff --git a/packages/eve/src/execution/tools/connection-tools.ts b/packages/eve/src/execution/tools/connection-tools.tsindex d0fdaf322..9ccea013a 100644--- a/packages/eve/src/execution/tools/connection-tools.ts+++ b/packages/eve/src/execution/tools/connection-tools.ts@@ -162,27 +162,31 @@ export function resolveConnectionTools(): DynamicToolSet | null {.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: {} }),- label: {- start: defineDurableCallback({ callback: connectionSearchLabel, 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: {},+ [CONNECTION_SEARCH_TOOL_NAME]: frameworkTool(+ defineTool({+ description: CONNECTION_SEARCH_DESCRIPTION,+ inputSchema: CONNECTION_SEARCH_INPUT_SCHEMA,+ execute: defineDurableCallback({ callback: searchConnectionTools, closure: {} }),+ label: {+ start: defineDurableCallback({ callback: connectionSearchLabel, closure: {} }),+ },+ }),+ ),+ [CONNECTION_EXECUTE_TOOL_NAME]: frameworkTool(+ 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),}),- ...connectionExecuteApproval(approvals),- }),+ ),};}@@ -505,3 +509,4 @@ function requireConnection(: `Connection "${name}" is not available. Available connections: ${available.join(", ")}.`,);}+import { frameworkTool } from "#tools/provided/framework-tool.js";diff --git a/packages/eve/src/execution/tools/workflow/harness-definition.ts b/packages/eve/src/execution/tools/workflow/harness-definition.tsindex cef88b613..a683acd52 100644--- a/packages/eve/src/execution/tools/workflow/harness-definition.ts+++ b/packages/eve/src/execution/tools/workflow/harness-definition.ts@@ -40,6 +40,7 @@ export function createPreparedWorkflowToolHarnessDefinition(}return createWorkflowToolHarnessDefinition({definition: {+ frameworkTool: tool.kind !== "authored-tool" || tool.owner.kind === "framework",behavior: tool.behavior,description: tool.description,inputSchema: toInputSchema(tool.inputSchema) ?? UNSPECIFIED_INPUT_SCHEMA,diff --git a/packages/eve/src/harness/coordination.test.ts b/packages/eve/src/harness/coordination.test.tsindex 399052351..3f6daed28 100644--- a/packages/eve/src/harness/coordination.test.ts+++ b/packages/eve/src/harness/coordination.test.ts@@ -16,8 +16,47 @@ import { toolOutput } from "#tools/model-output.js";import { setTurnUsageState } from "#harness/turn-tag-state.js";import type { HarnessSession } from "#harness/types.js";import { isRuntimeWorkflowToolAction } from "#shared/action-types.js";+import { createPreparedWorkflowToolHarnessDefinition } from "#execution/tools/workflow/harness-definition.js";+import type { PreparedRuntimeDelegationTool } from "#runtime/sessions/turn.js";describe("createRuntimeActionRequestFromToolCall", () => {+ it.each(["subagent", "remote"] as const)(+ "retains %s dispatch identity for a background agent tool",+ (kind) => {+ const target =+ kind === "remote"+ ? {+ kind: "remote-agent-call" as const,+ remoteAgentName: "reviewer",+ nodeId: "reviewer-node",+ }+ : { kind: "subagent-call" as const, subagentName: "reviewer", nodeId: "reviewer-node" };+ const prepared: PreparedRuntimeDelegationTool = {+ kind,+ name: "reviewer",+ nodeId: "reviewer-node",+ logicalPath: "subagents/reviewer",+ sourceId: "reviewer",+ description: "Review a draft.",+ inputSchema: { type: "object" },+ behavior: { availability: [], handling: { kind: "dispatch", target } },+ };+ const tool = createPreparedWorkflowToolHarnessDefinition(prepared);+ const action = createRuntimeActionRequestFromToolCall({+ toolCall: {+ input: { message: "Review Alice's draft." },+ toolCallId: "review",+ toolName: "reviewer",+ },+ tools: new Map([["reviewer", tool]]),+ });+ expect(action).toMatchObject({+ kind: target.kind,+ nodeId: "reviewer-node",+ name: "reviewer",+ });+ },+ );const loadSkillCall = {input: { skill: "research" },toolCallId: "call-skill",@@ -179,7 +218,12 @@ describe("createRuntimeActionRequestFromToolCall", () => {]),}),).toEqual({- action: { callId: "call-deploy", input: {}, kind: "tool-call", toolName: "deploy" },+ action: {+ callId: "call-deploy",+ input: {},+ kind: "tool-call",+ toolName: "deploy",+ },});});diff --git a/packages/eve/src/harness/coordination.ts b/packages/eve/src/harness/coordination.tsindex d731fbd5d..4dc007d72 100644--- a/packages/eve/src/harness/coordination.ts+++ b/packages/eve/src/harness/coordination.ts@@ -361,7 +361,29 @@ export function createRuntimeActionRequestFromToolCall(input: {toolName: input.toolCall.toolName,});if (definition?.frameworkAction === "load-skill") {- return { callId: input.toolCall.toolCallId, input: toolInput, kind: "load-skill" };+ return {+ callId: input.toolCall.toolCallId,+ input: toolInput,+ kind: "load-skill",+ };+ }+ const handling = definition?.behavior?.handling;+ if (+ definition !== undefined &&+ handling?.kind === "dispatch" &&+ handling.target.kind !== "workflow-tool-call"+ ) {+ const target = handling.target;+ const common = {+ callId: input.toolCall.toolCallId,+ description: definition.description,+ input: toolInput,+ name: input.toolCall.toolName,+ nodeId: target.nodeId,+ };+ return target.kind === "remote-agent-call"+ ? { ...common, kind: "remote-agent-call", remoteAgentName: target.remoteAgentName }+ : { ...common, kind: "subagent-call", subagentName: target.subagentName };}const action: RuntimeActionRequest = {callId: input.toolCall.toolCallId,diff --git a/packages/eve/src/harness/execute-tool.ts b/packages/eve/src/harness/execute-tool.tsindex 7ba33bebd..4509fdaa6 100644--- a/packages/eve/src/harness/execute-tool.ts+++ b/packages/eve/src/harness/execute-tool.ts@@ -23,6 +23,7 @@ export interface HarnessToolDefinition {readonly execute?: (input: any, options: ToolExecuteOptions) => any;/** Optional JSON input substituted when this tool starts its workflow body. */readonly executeInput?: (input: unknown) => JsonValue;+ readonly frameworkTool?: boolean;readonly frameworkAction?: "load-skill" | "task-cancel" | "task-wait";readonly inputSchema: FlexibleSchema;readonly name: string;diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.tsindex 56be252b0..13e2b1cc7 100644--- a/packages/eve/src/harness/tool-loop.test.ts+++ b/packages/eve/src/harness/tool-loop.test.ts@@ -10290,6 +10290,7 @@ describe("createToolLoopHarness", () => {}),runInContext,{},+ expect.any(Function),);const bridge = mockCreateAiSdkHookBridge.mock.results[0]!.value;const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as {diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex 524516627..3538508cf 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -524,9 +524,11 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {// turn's text isn't posted as their reply. A person reads a root session.const hidesHeldText = hasDelegatedCaller || store?.get(ScheduleIdKey) !== undefined;let activeAttemptScope: InstrumentationAttempt | undefined;+ let frameworkToolNames = new Set<string>();const instrumentedEmit =stepInstrumentation?.createHandleEvent({getAttemptScope: () => activeAttemptScope,+ isFrameworkTool: (name) => frameworkToolNames.has(name),handleEvent: baseEmit,turnId: activeTurnId(emissionState),}) ?? baseEmit;@@ -1469,6 +1471,11 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {};}+ frameworkToolNames = new Set(+ [...presentationTools]+ .filter(([, tool]) => tool.frameworkTool === true)+ .map(([name]) => name),+ );return { effectiveTools, modelTools, presentationTools };};@@ -1567,6 +1574,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {const instrumentationTurnId = activeTurnId(emissionState);const attempt = stepInstrumentation?.prepareAttempt({+ isFrameworkTool: (name) => frameworkToolNames.has(name),attemptIndex: opts.attemptIndex,runtimeContext: telemetryRuntimeContext,stepIndex: emissionState.stepIndex,diff --git a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.tsindex d372281a8..ad458f166 100644--- a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts+++ b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.test.ts@@ -665,6 +665,7 @@ describe("createAiSdkHookBridge", () => {{callId: "tool-1",idempotencyKey: `tool:${scope.attemptId}:tool-1:0`,+ frameworkTool: false,input: { q: "eve" },scope,toolName: "search",@@ -702,7 +703,7 @@ describe("createAiSdkHookBridge", () => {name: "metadata-only",},]);- const bridge = createAiSdkHookBridge(scope, hooks);+ const bridge = createAiSdkHookBridge(scope, hooks, undefined, undefined, () => true);const toolCall = { input: { q: "eve" }, toolCallId: "tool-1", toolName: "search" };await Reflect.apply(bridge.onLanguageModelCallStart!, bridge, [@@ -736,6 +737,9 @@ describe("createAiSdkHookBridge", () => {]);expect(modelStarted.mock.calls[0]?.[0].input).toBeUndefined();+ expect(toolStarted.mock.calls[0]?.[0]).toMatchObject({+ frameworkTool: true,+ });expect(modelCompleted.mock.calls[0]?.[0].content).toBeUndefined();// Structure survives: usage, the finish reason, and the tool's identity are// not what was said.diff --git a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.tsindex b46ce76ac..a0097eecb 100644--- a/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts+++ b/packages/eve/src/instrumentation/ai-sdk-hook-bridge.ts@@ -32,6 +32,7 @@ interface AttemptState {readonly runtimeContext?: Readonly<Record<string, unknown>>;readonly scope: InstrumentationAttemptScope;readonly toolKeys: Map<string, string>;+ readonly isFrameworkTool?: (name: string) => boolean;operation?: InstrumentationOperationRef;// Only the number is kept: it disambiguates call identities within an attempt.stepNumber?: number;@@ -48,6 +49,7 @@ export function createAiSdkHookBridge(hooks: InstrumentationHooks,runInContext: InstrumentationContextRunner = directRunInContext,runtimeContext?: Readonly<Record<string, unknown>>,+ isFrameworkTool?: (name: string) => boolean,): Telemetry {const state: AttemptState = {capturesInputs: hooks.capturesInputs ?? hooks.capturesContent,@@ -61,6 +63,7 @@ export function createAiSdkHookBridge(: undefined,scope,toolKeys: new Map(),+ isFrameworkTool,};const nextModelCallKey = (stepNumber: number): string => {const callIndex = state.modelCallIndexes.get(stepNumber) ?? 0;@@ -304,6 +307,7 @@ function toToolCallStarted(): InstrumentationToolCallStartedEvent {return Object.freeze({callId: source.toolCall.toolCallId,+ frameworkTool: state.isFrameworkTool?.(source.toolCall.toolName) === true,idempotencyKey,input: state.capturesInputs ? source.toolCall.input : undefined,scope: state.scope,diff --git a/packages/eve/src/instrumentation/dispatch.ts b/packages/eve/src/instrumentation/dispatch.tsindex 40a292b5b..157e06fc3 100644--- a/packages/eve/src/instrumentation/dispatch.ts+++ b/packages/eve/src/instrumentation/dispatch.ts@@ -86,6 +86,16 @@ export function createInstrumentationDispatcher();const failure = terminalActionFailure(snapshot);for (const action of pendingActions) {+ if (action.toolCall !== undefined) {+ await publish(action.toolCall);+ await publish({+ type: "tool.call.failed",+ idempotencyKey: action.toolCall.idempotencyKey,+ scope: action.scope,+ completedAtMs: Date.now(),+ error: failure.error,+ });+ }await publish({...failure,idempotencyKey: action.idempotencyKey,diff --git a/packages/eve/src/instrumentation/lifecycle.ts b/packages/eve/src/instrumentation/lifecycle.tsindex 085037e5a..c68db4ea0 100644--- a/packages/eve/src/instrumentation/lifecycle.ts+++ b/packages/eve/src/instrumentation/lifecycle.ts@@ -82,17 +82,6 @@ export type InstrumentationContentPart =readonly toolName: string;};-/**- * What eve dispatched an action as. The model sees every action as a tool, so- * this is the only thing that separates a subagent or remote-agent call from an- * ordinary tool in a trace.- */-export type InstrumentationActionKind =- | "load-skill"- | "remote-agent-call"- | "subagent-call"- | "tool-call";-/*** How one action ended.*@@ -463,7 +452,16 @@ export type InstrumentationModelCallTerminalEvent =export type InstrumentationToolOutput = InstrumentationActionOutput;+/** How eve dispatches the action. */+export type InstrumentationActionKind =+ | "load-skill"+ | "remote-agent-call"+ | "subagent-call"+ | "tool-call";+export interface InstrumentationToolCallStartedEvent {+ readonly frameworkTool?: boolean;+ readonly startedAtMs?: number;readonly type: "tool.call.started";readonly callId: string;readonly idempotencyKey: string;@@ -473,6 +471,7 @@ export interface InstrumentationToolCallStartedEvent {}export interface InstrumentationToolCallCompletedEvent {+ readonly completedAtMs?: number;readonly type: "tool.call.completed";/** How long the tool's `execute` ran, in milliseconds, when the publisher measured it. */readonly durationMs?: number;@@ -482,6 +481,7 @@ export interface InstrumentationToolCallCompletedEvent {}export interface InstrumentationToolCallFailedEvent {+ readonly completedAtMs?: number;readonly type: "tool.call.failed";/** Content. Absent unless this provider's trace policy records this direction. */readonly error?: unknown;diff --git a/packages/eve/src/instrumentation/native-events.test.ts b/packages/eve/src/instrumentation/native-events.test.tsindex 6c5a067d1..1538d58af 100644--- a/packages/eve/src/instrumentation/native-events.test.ts+++ b/packages/eve/src/instrumentation/native-events.test.ts@@ -396,6 +396,7 @@ describe("createInstrumentationHandleEvent", () => {input: { task: "research" },kind: "subagent-call",name: "delegate",+ isWorkflowTool: true,scope,type: "action.started",},@@ -416,6 +417,7 @@ describe("createInstrumentationHandleEvent", () => {input: { task: "analyze" },kind: "remote-agent-call",name: "remote",+ isWorkflowTool: true,scope,type: "action.started",},@@ -441,7 +443,12 @@ describe("createInstrumentationHandleEvent", () => {type: "action.started",},]);- expect(events[5]).toMatchObject({+ const terminals = events.filter(+ (event) =>+ (event as { type: string }).type === "action.failed" ||+ (event as { type: string }).type === "action.completed",+ );+ expect(terminals[0]).toMatchObject({errorCode: "ACTION_RESULT_FAILED",idempotencyKey: actionIdempotencyKey("session-1", "turn-1", "delegate-1"),outcome: "failed",@@ -454,7 +461,7 @@ describe("createInstrumentationHandleEvent", () => {outputTokens: 2,},});- expect(events[6]).toEqual({+ expect(terminals[1]).toEqual({acceptedAtMs: 1_234,idempotencyKey: actionIdempotencyKey("session-1", "turn-1", "remote-1"),outcome: "completed",@@ -468,7 +475,7 @@ describe("createInstrumentationHandleEvent", () => {outputTokens: 5,},});- expect(events[7]).toEqual({+ expect(terminals[2]).toEqual({acceptedAtMs: undefined,idempotencyKey: actionIdempotencyKey("session-1", "turn-1", "add-1"),outcome: "completed",@@ -477,7 +484,7 @@ describe("createInstrumentationHandleEvent", () => {type: "action.completed",usage: undefined,});- expect(events).toHaveLength(8);+ expect(events).toHaveLength(12);expect(events.every(Object.isFrozen)).toBe(true);});diff --git a/packages/eve/src/instrumentation/native-events.ts b/packages/eve/src/instrumentation/native-events.tsindex ccf64c53d..f949991b8 100644--- a/packages/eve/src/instrumentation/native-events.ts+++ b/packages/eve/src/instrumentation/native-events.ts@@ -12,12 +12,14 @@ import type {InstrumentationPointEvent,InstrumentationTraceContext,InstrumentationUsage,+ InstrumentationToolCallCompletedEvent,} from "#instrumentation/lifecycle.js";import {actionIdempotencyKey,inputIdempotencyKey,sessionIdempotencyKey,turnIdempotencyKey,+ toolCallIdempotencyKey,} from "#instrumentation/lifecycle.js";import {rememberInstrumentationActionScope,@@ -36,6 +38,7 @@ import {import type { ChannelAudience } from "#shared/channel-audience.js";export interface CreateInstrumentationHandleEventInput {+ readonly isFrameworkTool?: (name: string) => boolean;readonly traceSessionId?: string;readonly agentName?: string;readonly channelKind?: string;@@ -204,10 +207,29 @@ async function publishActionStarts(const capturesInputs = hooks.capturesInputs ?? hooks.capturesContent;for (const action of event.data.actions) {+ const deferred =+ isRuntimeWorkflowToolAction(action) ||+ action.kind === "subagent-call" ||+ action.kind === "remote-agent-call";const idempotencyKey = actionIdempotencyKey(input.sessionId, event.data.turnId, action.callId);if (published.has(idempotencyKey)) continue;published.add(idempotencyKey);- rememberInstrumentationActionScope(idempotencyKey, scope);+ rememberInstrumentationActionScope(+ idempotencyKey,+ scope,+ deferred+ ? {+ type: "tool.call.started",+ callId: action.callId,+ toolName: actionName(action),+ frameworkTool: input.isFrameworkTool?.(actionName(action)) === true,+ scope,+ idempotencyKey: toolCallIdempotencyKey(scope, action.callId, 0),+ startedAtMs: Date.now(),+ input: capturesInputs ? action.input : undefined,+ }+ : undefined,+ );await hooks.publish(Object.freeze({callId: action.callId,@@ -217,7 +239,7 @@ async function publishActionStarts(startedAtMs,idempotencyKey,input: capturesInputs ? action.input : undefined,- ...(isRuntimeWorkflowToolAction(action) ? { isWorkflowTool: true } : undefined),+ ...(deferred ? { isWorkflowTool: true } : undefined),kind: action.kind === "workflow-tool-call" ? "tool-call" : action.kind,name: actionName(action),scope,@@ -239,6 +261,24 @@ async function publishActionTerminal(if (correlation === undefined) return;const { idempotencyKey, scope } = correlation;const capturesOutputs = hooks.capturesOutputs ?? hooks.capturesContent;+ if (correlation.toolCall !== undefined) {+ await hooks.publish(Object.freeze(correlation.toolCall));+ await hooks.publish(+ Object.freeze({+ type: "tool.call.completed",+ idempotencyKey: correlation.toolCall.idempotencyKey,+ scope,+ completedAtMs:+ contextStorage.getStore()?.get(RuntimeActionSettlementTimesKey)?.[+ event.data.result.callId+ ] ?? Date.now(),+ output:+ event.data.status === "completed"+ ? { type: "result", output: capturesOutputs ? event.data.result.output : undefined }+ : { type: "error", error: capturesOutputs ? event.data.result.output : undefined },+ } satisfies InstrumentationToolCallCompletedEvent),+ );+ }if (event.data.status === "completed") {await hooks.publish(diff --git a/packages/eve/src/instrumentation/runtime.ts b/packages/eve/src/instrumentation/runtime.tsindex 634e03cea..95ecfcf02 100644--- a/packages/eve/src/instrumentation/runtime.ts+++ b/packages/eve/src/instrumentation/runtime.ts@@ -12,7 +12,8 @@ import type {InstrumentationTraceSeed,InstrumentationTurnStartedEvent,} from "#instrumentation/lifecycle.js";-import { attemptIdempotencyKey } from "#instrumentation/lifecycle.js";+import { attemptIdempotencyKey, toolCallIdempotencyKey } from "#instrumentation/lifecycle.js";+import { findInstrumentationActionScopeForCall } from "#instrumentation/state.js";import {buildTelemetryRuntimeContext,snapshotInstrumentationRuntimeContext,@@ -96,6 +97,7 @@ export interface InstrumentationStepScope<TSession> {>,) => HandleEventFn | undefined;readonly prepareAttempt: (input: {+ readonly isFrameworkTool?: (name: string) => boolean;readonly attemptIndex: number;readonly runtimeContext?: Readonly<Record<string, unknown>>;readonly stepIndex: number;@@ -173,6 +175,15 @@ export interface SessionInstrumentation {}export interface ExecutionInstrumentation {+ readonly instrumentTaskToolCall: (input: {+ readonly callId: string;+ readonly toolName: "task_wait" | "task_cancel";+ readonly startedAtMs: number;+ readonly completedAtMs: number;+ readonly input: unknown;+ readonly output?: unknown;+ readonly failed?: boolean;+ }) => Promise<void>;readonly createHandleEvent: (input: {readonly handleEvent?: HandleEventFn;readonly turnId?: string;@@ -435,6 +446,7 @@ export function bindInstrumentationRuntime(hooks,runtime.runInContext,attemptInput.runtimeContext,+ attemptInput.isFrameworkTool,);return {complete: () =>@@ -496,6 +508,46 @@ export function bindInstrumentationRuntime(};};return {+ async instrumentTaskToolCall(input) {+ const correlation = findInstrumentationActionScopeForCall(+ boundSession.sessionId,+ input.callId,+ );+ if (correlation === undefined) return;+ const hooks = bindHooks(readSessionContext());+ const scope = correlation.scope;+ const idempotencyKey = toolCallIdempotencyKey(scope, input.callId, 0);+ await hooks.publish({+ type: "tool.call.started",+ callId: input.callId,+ idempotencyKey,+ scope,+ toolName: input.toolName,+ startedAtMs: input.startedAtMs,+ frameworkTool: true,+ input: (hooks.capturesInputs ?? hooks.capturesContent) ? input.input : undefined,+ });+ if (input.failed) {+ await hooks.publish({+ type: "tool.call.failed",+ idempotencyKey,+ scope,+ completedAtMs: input.completedAtMs,+ });+ } else {+ await hooks.publish({+ type: "tool.call.completed",+ idempotencyKey,+ scope,+ completedAtMs: input.completedAtMs,+ durationMs: input.completedAtMs - input.startedAtMs,+ output: {+ type: "result",+ output: (hooks.capturesOutputs ?? hooks.capturesContent) ? input.output : undefined,+ },+ });+ }+ },createHandleEvent: (input) => {const sessionContext = readSessionContext();return createInstrumentationHandleEvent({diff --git a/packages/eve/src/instrumentation/state.ts b/packages/eve/src/instrumentation/state.tsindex 63b7a5894..cec0f8973 100644--- a/packages/eve/src/instrumentation/state.ts+++ b/packages/eve/src/instrumentation/state.ts@@ -29,6 +29,7 @@ export interface InstrumentationStateOwner {type InstrumentationStateMap = Readonly<Record<string, InstrumentationStateRecord>>;interface InstrumentationActionState {+ readonly toolCall?: import("#instrumentation/lifecycle.js").InstrumentationToolCallStartedEvent;readonly scope: InstrumentationAttemptScope;}type InstrumentationActionStateMap = Readonly<Record<string, InstrumentationActionState>>;@@ -191,10 +192,11 @@ function releaseMatchingInstrumentationState(export function rememberInstrumentationActionScope(idempotencyKey: string,scope: InstrumentationAttemptScope,+ toolCall?: InstrumentationActionState["toolCall"],): void {writeContextKey(InstrumentationActionStateKey, (state) => ({...state,- [idempotencyKey]: { scope },+ [idempotencyKey]: { scope, toolCall },}));}@@ -224,6 +226,7 @@ export function takeInstrumentationInputScope(}interface InstrumentationActionCorrelation {+ readonly toolCall?: InstrumentationActionState["toolCall"];readonly idempotencyKey: string;readonly scope: InstrumentationAttemptScope;}@@ -237,7 +240,8 @@ export function findInstrumentationActionScopeForCall(for (const candidate of Object.values(actions)) {const idempotencyKey = `action:${sessionId}:${candidate.scope.turnId}:${callId}`;const action = actions[idempotencyKey];- if (action !== undefined) return { idempotencyKey, scope: action.scope };+ if (action !== undefined)+ return { idempotencyKey, scope: action.scope, toolCall: action.toolCall };}return undefined;}@@ -266,7 +270,11 @@ export function takeInstrumentationActionScopes(action.scope.sessionId === sessionId &&(turnId === undefined || action.scope.turnId === turnId),)- .map(([idempotencyKey, action]) => ({ idempotencyKey, scope: action.scope }));+ .map(([idempotencyKey, action]) => ({+ idempotencyKey,+ scope: action.scope,+ toolCall: action.toolCall,+ }));if (correlations.length === 0) return [];const keys = new Set(correlations.map((correlation) => correlation.idempotencyKey));writeContextKey(InstrumentationActionStateKey, (state) => {@@ -375,7 +383,10 @@ function deserializeActionStates(data: unknown): InstrumentationActionStateMap {!Array.isArray(record["scope"])? (record["scope"] as InstrumentationAttemptScope): (value as InstrumentationAttemptScope);- actions[idempotencyKey] = { scope };+ actions[idempotencyKey] = {+ scope,+ toolCall: record.toolCall as InstrumentationActionState["toolCall"],+ };}return actions;}diff --git a/packages/eve/src/runtime/resolve-tool.test.ts b/packages/eve/src/runtime/resolve-tool.test.tsindex ed4b3f360..6cb3b4bfc 100644--- a/packages/eve/src/runtime/resolve-tool.test.ts+++ b/packages/eve/src/runtime/resolve-tool.test.ts@@ -8,6 +8,9 @@ import { toolResultFrom } from "#public/tools/result.js";import { resolveToolDefinition } from "#runtime/resolve-tool.js";import type { RuntimeActionResult } from "#shared/action-types.js";import { defineTool } from "#tools/definition.js";+import { sleep } from "#tools/provided/sleep.js";+import { noReply } from "#tools/provided/no-reply.js";+import { isFrameworkTool } from "#tools/provided/framework-tool.js";const definition: CompiledToolDefinition = {description: "Deploy a project.",@@ -33,6 +36,25 @@ function moduleMap(value: unknown): CompiledModuleMap {}describe("resolveToolDefinition", () => {+ it.each([+ { tool: sleep(), action: "sleep", workflow: true },+ { tool: noReply(), action: "no_reply", workflow: false },+ ])(+ "marks $action after an author spreads and renames the provided definition",+ async ({ tool, workflow }) => {+ const compiled = { ...definition, description: tool.description };+ if (workflow)+ compiled.behavior = {+ availability: [],+ handling: { kind: "workflow-tool", entryPoint: "execute", workflowId: "sleep-workflow" },+ };+ const resolved = await resolveToolDefinition(compiled, moduleMap({ ...tool }), undefined, {+ kind: "application",+ });+ expect(resolved.name).toBe("deploy");+ expect(isFrameworkTool(resolved)).toBe(true);+ },+ );it("reattaches authored label callbacks", async () => {const resolved = await resolveToolDefinition(definition,diff --git a/packages/eve/src/runtime/resolve-tool.ts b/packages/eve/src/runtime/resolve-tool.tsindex a3d20439b..a3e35572d 100644--- a/packages/eve/src/runtime/resolve-tool.ts+++ b/packages/eve/src/runtime/resolve-tool.ts@@ -1,4 +1,5 @@import type { CompiledToolDefinition } from "#compiler/manifest.js";+import { isFrameworkTool, frameworkTool } from "#tools/provided/framework-tool.js";import type { CompiledModuleMap } from "#compiler/module-map.js";import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";import { normalizeApproval } from "#internal/authored-definition/approval.js";@@ -26,7 +27,7 @@ export async function resolveToolDefinition(owner: AgentSourceOwner,): Promise<ResolvedToolDefinition> {if (!definition.hasExecute) {- return {+ const resolved: ResolvedToolDefinition = {availableInSubagents: definition.availableInSubagents,behavior: definition.behavior,description: definition.description,@@ -38,6 +39,9 @@ export async function resolveToolDefinition(sourceId: definition.sourceId,sourceKind: "module",};+ return definition.behavior?.handling?.kind === "provider-tool"+ ? frameworkTool(resolved)+ : resolved;}try {const resolvedExportValue = await loadResolvedModuleExport({@@ -77,7 +81,7 @@ export async function resolveToolDefinition(? undefined: (input: unknown) => createWorkflowProgramExecuteInput(workflowProgram, input);- return {+ const resolved: ResolvedToolDefinition = {availableInSubagents: definition.availableInSubagents,behavior: definition.behavior,description: definition.description,@@ -93,6 +97,7 @@ export async function resolveToolDefinition(sourceKind: "module",...extractOptionalHooks(resolvedRecord, definition),};+ return isFrameworkTool(resolvedRecord) ? frameworkTool(resolved) : resolved;} catch (error) {if (error instanceof ResolveAgentError) {throw error;diff --git a/packages/eve/src/tools/framework/agent.ts b/packages/eve/src/tools/framework/agent.tsindex f6eb174a4..c4e95eca7 100644--- a/packages/eve/src/tools/framework/agent.ts+++ b/packages/eve/src/tools/framework/agent.ts@@ -6,19 +6,22 @@ import {import { attachToolBehavior } from "#tools/behavior.js";export const agent = attachToolBehavior(- stampToolDefinition(- {- description: AGENT_TOOL_DESCRIPTION,- inputSchema: SUBAGENT_TOOL_INPUT_SCHEMA,- execute(): never {- throw new Error(- 'The framework "agent" tool was executed directly. It must be resolved through the runtime tool registry, which dispatches it to the shared subagent workflow.',- );+ frameworkTool(+ stampToolDefinition(+ {+ description: AGENT_TOOL_DESCRIPTION,+ inputSchema: SUBAGENT_TOOL_INPUT_SCHEMA,+ execute(): never {+ throw new Error(+ 'The framework "agent" tool was executed directly. It must be resolved through the runtime tool registry, which dispatches it to the shared subagent workflow.',+ );+ },},- },- "defineTool",+ "defineTool",+ ),),{ availability: ["root-session"], handling: { action: "self-agent", kind: "dispatch" } },);export default agent;+import { frameworkTool } from "#tools/provided/framework-tool.js";diff --git a/packages/eve/src/tools/provided/agent-router.ts b/packages/eve/src/tools/provided/agent-router.tsindex ba6634c17..0491fd5cd 100644--- a/packages/eve/src/tools/provided/agent-router.ts+++ b/packages/eve/src/tools/provided/agent-router.ts@@ -16,10 +16,13 @@ export type AgentRouterTool = WorkflowTaskToolDefinition<AgentRouterInput, JsonV* agent targets. Each call runs as a task.*/export function agentRouter(): AgentRouterTool {- return defineWorkflowTool({- availableInSubagents: false,- description: AGENT_ROUTER_TOOL_DESCRIPTION,- inputSchema: AGENT_ROUTER_INPUT_SCHEMA,- task: runAgentRouterTask,- });+ return frameworkTool(+ defineWorkflowTool({+ availableInSubagents: false,+ description: AGENT_ROUTER_TOOL_DESCRIPTION,+ inputSchema: AGENT_ROUTER_INPUT_SCHEMA,+ task: runAgentRouterTask,+ }),+ );}+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/ask-question.ts b/packages/eve/src/tools/provided/ask-question.tsindex 1e8b6a30e..334d87bb5 100644--- a/packages/eve/src/tools/provided/ask-question.ts+++ b/packages/eve/src/tools/provided/ask-question.ts@@ -117,11 +117,14 @@ const ASK_QUESTION_OUTPUT_SCHEMA = defineJsonSchema<AskQuestionOutput>({* message that does not answer the question withdraws it.*/export function askQuestion(): WorkflowExecuteToolDefinition<AskQuestionInput, AskQuestionOutput> {- return defineWorkflowTool({- description: ASK_QUESTION_TOOL_DESCRIPTION,- execute: executeAskQuestionTool,- inputSchema: ASK_QUESTION_INPUT_SCHEMA,- outputSchema: ASK_QUESTION_OUTPUT_SCHEMA,- toModelOutput: toInterruptibleModelOutput,- });+ return frameworkTool(+ defineWorkflowTool({+ description: ASK_QUESTION_TOOL_DESCRIPTION,+ execute: executeAskQuestionTool,+ inputSchema: ASK_QUESTION_INPUT_SCHEMA,+ outputSchema: ASK_QUESTION_OUTPUT_SCHEMA,+ toModelOutput: toInterruptibleModelOutput,+ }),+ );}+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/bash.ts b/packages/eve/src/tools/provided/bash.tsindex 6aa12d1bd..b8c9bec4e 100644--- a/packages/eve/src/tools/provided/bash.ts+++ b/packages/eve/src/tools/provided/bash.ts@@ -3,6 +3,7 @@ import {executeBashOnSandbox,type BashInput,} from "#execution/sandbox/bash.js";+import { frameworkTool } from "./framework-tool.js";import { toolLabel } from "#tools/tool-label.js";import { defineTool, type ToolDefinition } from "#tools/definition.js";import { defineJsonSchema } from "#tools/schema.js";@@ -89,16 +90,18 @@ export const BASH_OUTPUT_SCHEMA = defineJsonSchema<BashToolOutput>({* sandbox dependencies remain lazily loaded inside the execution layer, so the* top-level import here does not force those backends to initialize eagerly.*/-export const bash: ToolDefinition<BashToolInput, BashToolOutput> = defineTool({- label: { start: (input) => toolLabel("Run", input.command) },- description: `Execute a shell command in the shared workspace environment. A command still running after ${BASH_YIELD_SECONDS} seconds keeps running in the background and returns status "running" with its output so far and how to check on or stop it.`,- async execute(input, ctx) {- return await executeBashOnSandbox(await ctx.getSandbox(), input as BashInput, {- abortSignal: ctx.abortSignal,- });- },- inputSchema: BASH_INPUT_SCHEMA,- outputSchema: BASH_OUTPUT_SCHEMA,-});+export const bash: ToolDefinition<BashToolInput, BashToolOutput> = frameworkTool(+ defineTool({+ label: { start: (input) => toolLabel("Run", input.command) },+ description: `Execute a shell command in the shared workspace environment. A command still running after ${BASH_YIELD_SECONDS} seconds keeps running in the background and returns status "running" with its output so far and how to check on or stop it.`,+ async execute(input, ctx) {+ return await executeBashOnSandbox(await ctx.getSandbox(), input as BashInput, {+ abortSignal: ctx.abortSignal,+ });+ },+ inputSchema: BASH_INPUT_SCHEMA,+ outputSchema: BASH_OUTPUT_SCHEMA,+ }),+);export default bash;diff --git a/packages/eve/src/tools/provided/framework-tool.ts b/packages/eve/src/tools/provided/framework-tool.tsnew file mode 100644index 000000000..a5c9ac588--- /dev/null+++ b/packages/eve/src/tools/provided/framework-tool.ts@@ -0,0 +1,11 @@+const FRAMEWORK_TOOL = Symbol.for("eve.framework-tool");++/** Keeps framework identity on definitions even when their runtime names change. */+export function frameworkTool<T extends object>(definition: T): T {+ Object.defineProperty(definition, FRAMEWORK_TOOL, { enumerable: true, value: true });+ return definition;+}++export function isFrameworkTool(definition: object): boolean {+ return Reflect.get(definition, FRAMEWORK_TOOL) === true;+}diff --git a/packages/eve/src/tools/provided/glob.ts b/packages/eve/src/tools/provided/glob.tsindex 6faaac663..d9048ef71 100644--- a/packages/eve/src/tools/provided/glob.ts+++ b/packages/eve/src/tools/provided/glob.ts@@ -61,21 +61,24 @@ export const GLOB_OUTPUT_SCHEMA = defineJsonSchema<GlobToolOutput>({/*** Framework-owned executor that delegates to the default sandbox.*/-export const glob: ToolDefinition<GlobToolInput, GlobToolOutput> = defineTool({- label: { start: (input) => toolLabel("Find", input.pattern) },- description: [- "Fast file pattern matching tool that works with any codebase size.",- "",- "Usage:",- '- Supports glob patterns like "**/*.js" or "src/**/*.ts".',- "- Returns matching file paths.",- "- Call this tool in parallel when you know there are multiple patterns to search for.",- ].join("\n"),- async execute(input, ctx) {- return await executeGlobOnSandbox(await ctx.getSandbox(), input as GlobInput);- },- inputSchema: GLOB_INPUT_SCHEMA,- outputSchema: GLOB_OUTPUT_SCHEMA,-});+export const glob: ToolDefinition<GlobToolInput, GlobToolOutput> = frameworkTool(+ defineTool({+ label: { start: (input) => toolLabel("Find", input.pattern) },+ description: [+ "Fast file pattern matching tool that works with any codebase size.",+ "",+ "Usage:",+ '- Supports glob patterns like "**/*.js" or "src/**/*.ts".',+ "- Returns matching file paths.",+ "- Call this tool in parallel when you know there are multiple patterns to search for.",+ ].join("\n"),+ async execute(input, ctx) {+ return await executeGlobOnSandbox(await ctx.getSandbox(), input as GlobInput);+ },+ inputSchema: GLOB_INPUT_SCHEMA,+ outputSchema: GLOB_OUTPUT_SCHEMA,+ }),+);export default glob;+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/grep.ts b/packages/eve/src/tools/provided/grep.tsindex 708b15484..a0fbb0aca 100644--- a/packages/eve/src/tools/provided/grep.ts+++ b/packages/eve/src/tools/provided/grep.ts@@ -85,24 +85,27 @@ export const GREP_OUTPUT_SCHEMA = defineJsonSchema<GrepToolOutput>({/*** Framework-owned executor that delegates to the default sandbox.*/-export const grep: ToolDefinition<GrepToolInput, GrepToolOutput> = defineTool({- label: { start: (input) => toolLabel("Search", input.pattern) },- description: [- "Fast content search tool that works with any codebase size.",- "",- "Usage:",- "- Searches file contents using regular expressions.",- '- Supports full regex syntax (e.g. "log.*Error", "function\\s+\\w+").',- '- Filter files by pattern with the glob parameter (e.g. "*.js", "*.{ts,tsx}").',- "- Returns matching lines with file paths and line numbers.",- "- Call this tool in parallel when you have multiple independent searches.",- "- Any line longer than 2000 characters is truncated.",- ].join("\n"),- async execute(input, ctx) {- return await executeGrepOnSandbox(await ctx.getSandbox(), input as GrepInput);- },- inputSchema: GREP_INPUT_SCHEMA,- outputSchema: GREP_OUTPUT_SCHEMA,-});+export const grep: ToolDefinition<GrepToolInput, GrepToolOutput> = frameworkTool(+ defineTool({+ label: { start: (input) => toolLabel("Search", input.pattern) },+ description: [+ "Fast content search tool that works with any codebase size.",+ "",+ "Usage:",+ "- Searches file contents using regular expressions.",+ '- Supports full regex syntax (e.g. "log.*Error", "function\\s+\\w+").',+ '- Filter files by pattern with the glob parameter (e.g. "*.js", "*.{ts,tsx}").',+ "- Returns matching lines with file paths and line numbers.",+ "- Call this tool in parallel when you have multiple independent searches.",+ "- Any line longer than 2000 characters is truncated.",+ ].join("\n"),+ async execute(input, ctx) {+ return await executeGrepOnSandbox(await ctx.getSandbox(), input as GrepInput);+ },+ inputSchema: GREP_INPUT_SCHEMA,+ outputSchema: GREP_OUTPUT_SCHEMA,+ }),+);export default grep;+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/load-skill.ts b/packages/eve/src/tools/provided/load-skill.tsindex 24d01429b..cdca58c47 100644--- a/packages/eve/src/tools/provided/load-skill.ts+++ b/packages/eve/src/tools/provided/load-skill.ts@@ -8,27 +8,30 @@ import { defineTool } from "#tools/definition.js";import { attachToolBehavior } from "#tools/behavior.js";export const loadSkill = attachToolBehavior(- defineTool({- label: {- start: (input) => {- const skill =- typeof input === "object" && input !== null ? Reflect.get(input, "skill") : undefined;- return typeof skill === "string" && skill.trim() !== ""- ? `Load skill: ${displayTitle(skill.trim())}`- : "Load skill";+ frameworkTool(+ defineTool({+ label: {+ start: (input) => {+ const skill =+ typeof input === "object" && input !== null ? Reflect.get(input, "skill") : undefined;+ return typeof skill === "string" && skill.trim() !== ""+ ? `Load skill: ${displayTitle(skill.trim())}`+ : "Load skill";+ },},- },- description: [- "Load the full instructions for one available skill by name or id.",- "Use this tool when the request clearly matches a listed skill description or when the user explicitly asks for that skill.",- "Loading adds the skill instructions to the current turn.",- 'Choose the "skill" value from the Available skills block.',- ].join(" "),- execute: executeLoadSkill,- inputSchema: SKILL_INPUT_SCHEMA,- outputSchema: SKILL_OUTPUT_SCHEMA,- }),+ description: [+ "Load the full instructions for one available skill by name or id.",+ "Use this tool when the request clearly matches a listed skill description or when the user explicitly asks for that skill.",+ "Loading adds the skill instructions to the current turn.",+ 'Choose the "skill" value from the Available skills block.',+ ].join(" "),+ execute: executeLoadSkill,+ inputSchema: SKILL_INPUT_SCHEMA,+ outputSchema: SKILL_OUTPUT_SCHEMA,+ }),+ ),{ availability: [], presentation: "load-skill" },);export default loadSkill;+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/no-reply.ts b/packages/eve/src/tools/provided/no-reply.tsindex ae9e49fae..dc32d1c41 100644--- a/packages/eve/src/tools/provided/no-reply.ts+++ b/packages/eve/src/tools/provided/no-reply.ts@@ -22,21 +22,24 @@ export interface NoReplyToolInput {* channels and schedules post nothing. Only root sessions receive it.*/export function noReply(): ToolDefinition<NoReplyToolInput, string> {- return defineTool<NoReplyToolInput, string>({- availableInSubagents: false,- description: NO_REPLY_TOOL_DESCRIPTION,- endsTurn: true,- execute: () => "No reply was sent.",- inputSchema: {- type: "object",- properties: {- reason: {- type: "string",- description:- "Why no reply is needed. Kept in the session history and traces; never sent.",+ return frameworkTool(+ defineTool<NoReplyToolInput, string>({+ availableInSubagents: false,+ description: NO_REPLY_TOOL_DESCRIPTION,+ endsTurn: true,+ execute: () => "No reply was sent.",+ inputSchema: {+ type: "object",+ properties: {+ reason: {+ type: "string",+ description:+ "Why no reply is needed. Kept in the session history and traces; never sent.",+ },},+ additionalProperties: false,},- additionalProperties: false,- },- });+ }),+ );}+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/read-file.ts b/packages/eve/src/tools/provided/read-file.tsindex 4ec60d832..850d0ebac 100644--- a/packages/eve/src/tools/provided/read-file.ts+++ b/packages/eve/src/tools/provided/read-file.ts@@ -85,54 +85,58 @@ export const READ_FILE_OUTPUT_SCHEMA = defineJsonSchema<ReadFileToolOutput>({/*** Framework-owned executor that delegates to the default sandbox.*/-export const readFile: ToolDefinition<ReadFileToolInput, ReadFileToolOutput> = defineTool({- label: { start: (input) => toolLabel("Read", input.filePath) },- description: [- "Read a file from the local filesystem. If the path does not exist, an error is returned.",- "",- "Usage:",- "- The filePath parameter should be an absolute path or begin with $HOME/.",- "- By default, this tool returns up to 2000 lines from the start of the file.",- "- The offset parameter is the line number to start from (1-indexed).",- "- To read later sections, call this tool again with a larger offset.",- '- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents "foo\\n", you will receive "1: foo\\n".',- "- Any line longer than 2000 characters is truncated.",- "- PNG, JPEG, GIF, and WebP files up to 3 MiB are shown to you as images, including files named in `Attached file <path>` references.",- "- Call this tool in parallel when you know there are multiple files you want to read.",- "- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.",- ].join("\n"),- async execute(input, ctx) {- return await executeReadFileOnSandbox(await ctx.getSandbox(), input as ReadFileInput);- },- inputSchema: READ_FILE_INPUT_SCHEMA,- outputSchema: READ_FILE_OUTPUT_SCHEMA,- async toModelOutput(output) {- if (output.image === undefined) return toolOutput.json(output);- // The bytes load here rather than in `execute`, so `action.result` never- // carries them. The harness then stages this file part under its own name- // as a sandbox ref before it enters history.- const sandbox = await contextStorage.getStore()?.get(SandboxKey)?.get();- const bytes =- sandbox === undefined || sandbox === null- ? null- : await sandbox.readBinaryFile({- path: await resolveAbsoluteFilePath(sandbox, output.path),- });- if (bytes === null) return toolOutput.text(`${output.content} The image could not be loaded.`);- // A file replaced after `execute` would otherwise skip its size cap.- if (bytes.byteLength !== output.image.size) {- return toolOutput.text(- `${output.content} The image changed after it was read; read it again.`,- );- }- return toolOutput.content([- toolOutputPart.text(output.content),- toolOutputPart.file(Buffer.from(bytes).toString("base64"), {- filename: basename(output.path),- mediaType: output.image.mediaType,- }),- ]);- },-});+export const readFile: ToolDefinition<ReadFileToolInput, ReadFileToolOutput> = frameworkTool(+ defineTool({+ label: { start: (input) => toolLabel("Read", input.filePath) },+ description: [+ "Read a file from the local filesystem. If the path does not exist, an error is returned.",+ "",+ "Usage:",+ "- The filePath parameter should be an absolute path or begin with $HOME/.",+ "- By default, this tool returns up to 2000 lines from the start of the file.",+ "- The offset parameter is the line number to start from (1-indexed).",+ "- To read later sections, call this tool again with a larger offset.",+ '- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents "foo\\n", you will receive "1: foo\\n".',+ "- Any line longer than 2000 characters is truncated.",+ "- PNG, JPEG, GIF, and WebP files up to 3 MiB are shown to you as images, including files named in `Attached file <path>` references.",+ "- Call this tool in parallel when you know there are multiple files you want to read.",+ "- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.",+ ].join("\n"),+ async execute(input, ctx) {+ return await executeReadFileOnSandbox(await ctx.getSandbox(), input as ReadFileInput);+ },+ inputSchema: READ_FILE_INPUT_SCHEMA,+ outputSchema: READ_FILE_OUTPUT_SCHEMA,+ async toModelOutput(output) {+ if (output.image === undefined) return toolOutput.json(output);+ // The bytes load here rather than in `execute`, so `action.result` never+ // carries them. The harness then stages this file part under its own name+ // as a sandbox ref before it enters history.+ const sandbox = await contextStorage.getStore()?.get(SandboxKey)?.get();+ const bytes =+ sandbox === undefined || sandbox === null+ ? null+ : await sandbox.readBinaryFile({+ path: await resolveAbsoluteFilePath(sandbox, output.path),+ });+ if (bytes === null)+ return toolOutput.text(`${output.content} The image could not be loaded.`);+ // A file replaced after `execute` would otherwise skip its size cap.+ if (bytes.byteLength !== output.image.size) {+ return toolOutput.text(+ `${output.content} The image changed after it was read; read it again.`,+ );+ }+ return toolOutput.content([+ toolOutputPart.text(output.content),+ toolOutputPart.file(Buffer.from(bytes).toString("base64"), {+ filename: basename(output.path),+ mediaType: output.image.mediaType,+ }),+ ]);+ },+ }),+);export default readFile;+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/sleep.ts b/packages/eve/src/tools/provided/sleep.tsindex 2546eb906..84060723c 100644--- a/packages/eve/src/tools/provided/sleep.ts+++ b/packages/eve/src/tools/provided/sleep.ts@@ -59,11 +59,14 @@ const SLEEP_OUTPUT_SCHEMA = defineJsonSchema<SleepToolOutput>({* application runtime open. A new message ends the wait early.*/export function sleep(): WorkflowExecuteToolDefinition<SleepToolInput, SleepToolOutput> {- return defineWorkflowTool({- description: SLEEP_TOOL_DESCRIPTION,- execute: executeSleepTool,- inputSchema: SLEEP_INPUT_SCHEMA,- outputSchema: SLEEP_OUTPUT_SCHEMA,- toModelOutput: toInterruptibleModelOutput,- });+ return frameworkTool(+ defineWorkflowTool({+ description: SLEEP_TOOL_DESCRIPTION,+ execute: executeSleepTool,+ inputSchema: SLEEP_INPUT_SCHEMA,+ outputSchema: SLEEP_OUTPUT_SCHEMA,+ toModelOutput: toInterruptibleModelOutput,+ }),+ );}+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/task-cancel.ts b/packages/eve/src/tools/provided/task-cancel.tsindex 29cfaff38..ca28ada64 100644--- a/packages/eve/src/tools/provided/task-cancel.ts+++ b/packages/eve/src/tools/provided/task-cancel.ts@@ -12,6 +12,7 @@ export interface TaskCancelInput {/** `task_cancel`, offered to agents that can start tasks; the session answers each call. */export const taskCancelTool: HarnessToolDefinition = {+ frameworkTool: true,description: TASK_CANCEL_DESCRIPTION,frameworkAction: "task-cancel",inputSchema: defineJsonSchema<TaskCancelInput>({diff --git a/packages/eve/src/tools/provided/task-wait.ts b/packages/eve/src/tools/provided/task-wait.tsindex 5aa2ab12c..23aade637 100644--- a/packages/eve/src/tools/provided/task-wait.ts+++ b/packages/eve/src/tools/provided/task-wait.ts@@ -12,6 +12,7 @@ export interface TaskWaitInput {* call defers out of the model step and the session parks the turn itself.*/export const taskWaitTool: HarnessToolDefinition = {+ frameworkTool: true,description: TASK_WAIT_DESCRIPTION,frameworkAction: "task-wait",inputSchema: defineJsonSchema<TaskWaitInput>({diff --git a/packages/eve/src/tools/provided/web-fetch.ts b/packages/eve/src/tools/provided/web-fetch.tsindex 7c8b70b70..1a7eeb333 100644--- a/packages/eve/src/tools/provided/web-fetch.ts+++ b/packages/eve/src/tools/provided/web-fetch.ts@@ -50,24 +50,27 @@ export const WEB_FETCH_OUTPUT_SCHEMA = defineJsonSchema<WebFetchToolOutput>({additionalProperties: false,});-export const webFetch: ToolDefinition<WebFetchToolInput, WebFetchToolOutput> = defineTool({- label: { start: (input) => toolLabel("Fetch", input.url) },- description: [- "Fetch a webpage and return its content in the requested format. Use this to retrieve and analyze content from URLs.",- "",- "Usage notes:",- "- The URL must be a fully-formed valid URL starting with https://",- "- HTML responses are automatically converted to markdown or plain text based on the requested format",- '- Format options: "markdown" (default), "text", or "html"',- "- Default timeout is 30 seconds (max 120 seconds)",- "- Maximum response size is 5 MB; content is further capped at the shared tool-output budget (50 KB / 2000 lines)",- "- This tool is read-only and does not modify any files",- ].join("\n"),- async execute(input, ctx) {- return await executeWebFetchTool(input as WebFetchInput, { abortSignal: ctx.abortSignal });- },- inputSchema: WEB_FETCH_INPUT_SCHEMA,- outputSchema: WEB_FETCH_OUTPUT_SCHEMA,-});+export const webFetch: ToolDefinition<WebFetchToolInput, WebFetchToolOutput> = frameworkTool(+ defineTool({+ label: { start: (input) => toolLabel("Fetch", input.url) },+ description: [+ "Fetch a webpage and return its content in the requested format. Use this to retrieve and analyze content from URLs.",+ "",+ "Usage notes:",+ "- The URL must be a fully-formed valid URL starting with https://",+ "- HTML responses are automatically converted to markdown or plain text based on the requested format",+ '- Format options: "markdown" (default), "text", or "html"',+ "- Default timeout is 30 seconds (max 120 seconds)",+ "- Maximum response size is 5 MB; content is further capped at the shared tool-output budget (50 KB / 2000 lines)",+ "- This tool is read-only and does not modify any files",+ ].join("\n"),+ async execute(input, ctx) {+ return await executeWebFetchTool(input as WebFetchInput, { abortSignal: ctx.abortSignal });+ },+ inputSchema: WEB_FETCH_INPUT_SCHEMA,+ outputSchema: WEB_FETCH_OUTPUT_SCHEMA,+ }),+);export default webFetch;+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/web-search.test.ts b/packages/eve/src/tools/provided/web-search.test.tsindex 7c36da002..266003083 100644--- a/packages/eve/src/tools/provided/web-search.test.ts+++ b/packages/eve/src/tools/provided/web-search.test.ts@@ -4,7 +4,7 @@ import { webSearch } from "#tools/provided/web-search.js";describe("webSearch", () => {it.each(["parallel", "exa"] as const)("configures the %s provider", (provider) => {- expect(webSearch({ provider })).toEqual({+ expect(webSearch({ provider })).toMatchObject({kind: "eve:web-search-tool",provider,});diff --git a/packages/eve/src/tools/provided/web-search.ts b/packages/eve/src/tools/provided/web-search.tsindex f9ac474ac..81e7910e3 100644--- a/packages/eve/src/tools/provided/web-search.ts+++ b/packages/eve/src/tools/provided/web-search.ts@@ -1,4 +1,5 @@import type { WebSearchProvider } from "#shared/web-search.js";+import { frameworkTool } from "./framework-tool.js";export type { WebSearchProvider };@@ -37,10 +38,10 @@ export interface WebSearchToolDefinition {* ```*/export function webSearch(input: WebSearchToolInput): WebSearchToolDefinition {- return {+ return frameworkTool({kind: WEB_SEARCH_TOOL_KIND,provider: input.provider,- };+ });}/** Default provider-managed web search configuration. */diff --git a/packages/eve/src/tools/provided/workflow.ts b/packages/eve/src/tools/provided/workflow.tsindex 394d93371..e29c82dfb 100644--- a/packages/eve/src/tools/provided/workflow.ts+++ b/packages/eve/src/tools/provided/workflow.ts@@ -44,11 +44,13 @@ export function workflow(options: WorkflowToolOptions = {}): WorkflowTool {`The program may invoke at most ${String(normalized.maxSubagents)} agents.`,].join(" ");return attachWorkflowProgramOptions(- defineWorkflowTool({- description,- inputSchema: workflowInputSchema,- task: runWorkflowProgramTask,- }),+ frameworkTool(+ defineWorkflowTool({+ description,+ inputSchema: workflowInputSchema,+ task: runWorkflowProgramTask,+ }),+ ),normalized,);}@@ -63,3 +65,4 @@ function normalizeWorkflowToolOptions(options: WorkflowToolOptions): {maxSubagents: options.maxSubagents ?? DEFAULT_WORKFLOW_PROGRAM_MAX_SUBAGENTS,});}+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tools/provided/write-file.ts b/packages/eve/src/tools/provided/write-file.tsindex 6b6880b71..c8cc794a5 100644--- a/packages/eve/src/tools/provided/write-file.ts+++ b/packages/eve/src/tools/provided/write-file.ts@@ -45,23 +45,26 @@ export const WRITE_FILE_OUTPUT_SCHEMA = defineJsonSchema<WriteFileToolOutput>({/*** Framework-owned executor that delegates to the default sandbox.*/-export const writeFile: ToolDefinition<WriteFileToolInput, WriteFileToolOutput> = defineTool({- label: { start: (input) => toolLabel("Write", input.filePath) },- description: [- "Writes a file to the local filesystem.",- "",- "Usage:",- "- This tool will overwrite the existing file if there is one at the provided path.",- "- If this is an existing file, you MUST use the read_file tool first to read the file's contents. This tool will fail if you did not read the file first.",- "- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.",- "- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.",- "- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",- ].join("\n"),- async execute(input, ctx) {- return await executeWriteFileOnSandbox(await ctx.getSandbox(), input as WriteFileInput);- },- inputSchema: WRITE_FILE_INPUT_SCHEMA,- outputSchema: WRITE_FILE_OUTPUT_SCHEMA,-});+export const writeFile: ToolDefinition<WriteFileToolInput, WriteFileToolOutput> = frameworkTool(+ defineTool({+ label: { start: (input) => toolLabel("Write", input.filePath) },+ description: [+ "Writes a file to the local filesystem.",+ "",+ "Usage:",+ "- This tool will overwrite the existing file if there is one at the provided path.",+ "- If this is an existing file, you MUST use the read_file tool first to read the file's contents. This tool will fail if you did not read the file first.",+ "- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.",+ "- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.",+ "- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",+ ].join("\n"),+ async execute(input, ctx) {+ return await executeWriteFileOnSandbox(await ctx.getSandbox(), input as WriteFileInput);+ },+ inputSchema: WRITE_FILE_INPUT_SCHEMA,+ outputSchema: WRITE_FILE_OUTPUT_SCHEMA,+ }),+);export default writeFile;+import { frameworkTool } from "./framework-tool.js";diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.tsindex 5ae07e6ef..cb5518f33 100644--- a/packages/eve/src/tracing/agent-otel-provider.test.ts+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts@@ -1505,6 +1505,7 @@ describe("createAgentOtelInstrumentation", () => {"gen_ai.agent.name": "weather","gen_ai.operation.name": "execute_tool","gen_ai.tool.call.id": "tool-1",+ "agent.tool.is_framework": false,"gen_ai.tool.name": "weather","gen_ai.tool.type": "function",});diff --git a/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts b/packages/eve/src/tracing/agent-telemetry-contract.integration.test.tsindex c8f36431d..162ce2e7c 100644--- a/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts+++ b/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts@@ -54,6 +54,10 @@ import { emitNestedToolActions } from "#harness/nested-actions.js";import { createInstrumentationHandleEvent } from "#instrumentation/native-events.js";import { createActionResultEvent, createActionsRequestedEvent } from "#protocol/message.js";import type { JsonValue } from "#shared/json.js";+import { createPresentedRuntimeActionRequestFromToolCall } from "#harness/action-presentation.js";+import { taskWaitTool } from "#tools/provided/task-wait.js";+import { taskCancelTool } from "#tools/provided/task-cancel.js";+import { jsonSchema } from "ai";const traceContext = (agentName: string, audience: "public" | "private") => ({agentName,@@ -294,7 +298,237 @@ describe("exported agent telemetry contract", () => {}},);+ it.each([+ {+ tool: taskWaitTool,+ input: { timeoutSeconds: 30 },+ duration: 25_000,+ replacement: true,+ failed: false,+ },+ {+ tool: taskWaitTool,+ input: { timeoutSeconds: 0 },+ duration: 0,+ replacement: false,+ failed: false,+ },+ {+ tool: taskCancelTool,+ input: { taskId: "research" },+ duration: 0,+ replacement: false,+ failed: false,+ },+ { tool: taskWaitTool, input: {}, duration: 10_000, replacement: true, failed: true },+ ])(+ "exports $tool.name with its original duration (replacement=$replacement, failed=$failed)",+ async ({ tool, input, duration, replacement, failed }) => {+ vi.stubEnv("VERCEL_ENV", "preview");+ const first = createRuntime();+ let runtime = first;+ let ctx = contextFor("public");+ const scope = scopeFor("parent", "public");+ const startedAtMs = Date.now();+ const completedAtMs = startedAtMs + duration;+ try {+ await contextStorage.run(ctx, async () => {+ const binding = bindInstrumentationRuntime(first, ctx, {+ agentName: "parent",+ rootSessionId: "parent",+ sessionId: "parent",+ })!;+ await binding.preparePreamble({ sequence: 0, sessionStarted: false, turnId: "turn_0" });+ const emit = createInstrumentationHandleEvent({+ sessionId: "parent",+ hooks: first.hooks.forTrace!(traceContext("parent", "public")),+ handleEvent: async () => {},+ getAttemptScope: () => scope,+ })!;+ const action = createPresentedRuntimeActionRequestFromToolCall({+ toolCall: { type: "tool-call", input, toolCallId: "control", toolName: tool.name },+ tools: new Map([[tool.name, tool]]),+ }).action;+ await emit(+ createActionsRequestedEvent({+ actions: [action],+ sequence: 0,+ stepIndex: 0,+ turnId: "turn_0",+ }),+ );+ });+ if (replacement) {+ ctx = await deserializeContext(serializeContext(ctx));+ runtime = createRuntime();+ }+ await contextStorage.run(ctx, async () => {+ const binding = bindInstrumentationRuntime(runtime, ctx, {+ agentName: "parent",+ rootSessionId: "parent",+ sessionId: "parent",+ })!;+ await binding.instrumentTaskToolCall({+ callId: "control",+ toolName: tool.name as "task_wait" | "task_cancel",+ startedAtMs,+ completedAtMs,+ input,+ output: "Alice's research finished.",+ failed,+ });+ const emit = createInstrumentationHandleEvent({+ sessionId: "parent",+ hooks: runtime.hooks.forTrace!(traceContext("parent", "public")),+ handleEvent: async () => {},+ })!;+ await emit(+ createActionResultEvent({+ result: {+ callId: "control",+ kind: "tool-result",+ toolName: tool.name,+ output: "Alice's research finished.",+ },+ sequence: 0,+ stepIndex: 0,+ turnId: "turn_0",+ }),+ );+ });+ const spans = runtime.exporter.getFinishedSpans();+ const action = spans.find((span) => span.name === "agent.action")!;+ const execution = spans.find((span) => span.name === `execute_tool ${tool.name}`)!;+ expect(execution).toBeDefined();+ expect(execution.parentSpanContext?.spanId).toBe(action.spanContext().spanId);+ expect(execution.attributes["agent.tool.is_framework"]).toBe(true);+ expect(action.attributes).not.toHaveProperty("agent.action.origin");+ expect(action.attributes).not.toHaveProperty("agent.framework.action");+ expect(execution.startTime).toEqual([+ Math.floor(startedAtMs / 1_000),+ (startedAtMs % 1_000) * 1_000_000,+ ]);+ expect(execution.duration).toEqual([+ Math.floor(duration / 1_000),+ (duration % 1_000) * 1_000_000,+ ]);+ expect(execution.status.code).toBe(failed ? 2 : 0);+ expect(+ runtime.metadata.getFinishedSpans().find((span) => span.name === execution.name)+ ?.attributes,+ ).toMatchObject({+ "agent.tool.is_framework": true,+ });+ } finally {+ vi.unstubAllEnvs();+ await first.shutdown();+ if (runtime !== first) await runtime.shutdown();+ }+ },+ );+ it.each(["subagent-call", "remote-agent-call"] as const)(+ "exports deferred %s as a caller with a tool child after worker replacement",+ async (kind) => {+ vi.stubEnv("VERCEL_ENV", "preview");+ const first = createRuntime();+ const second = createRuntime();+ const ctx = contextFor("public");+ const scope = scopeFor("parent", "public");+ try {+ await contextStorage.run(ctx, async () => {+ await bindInstrumentationRuntime(first, ctx, {+ agentName: "parent",+ rootSessionId: "parent",+ sessionId: "parent",+ })!.preparePreamble({ sequence: 0, sessionStarted: false, turnId: "turn_0" });+ const action = createPresentedRuntimeActionRequestFromToolCall({+ toolCall: {+ type: "tool-call",+ input: { message: "Review Alice's draft." },+ toolCallId: "review",+ toolName: "reviewer",+ },+ tools: new Map([+ [+ "reviewer",+ {+ name: "reviewer",+ frameworkTool: true,+ description: "Review drafts.",+ inputSchema: jsonSchema({ type: "object" }),+ workflowId: "review-workflow",+ behavior: {+ availability: [],+ handling: {+ kind: "dispatch",+ target:+ kind === "subagent-call"+ ? { kind, nodeId: "reviewer-node", subagentName: "reviewer" }+ : { kind, nodeId: "reviewer-node", remoteAgentName: "reviewer" },+ },+ },+ },+ ],+ ]),+ }).action;+ await createInstrumentationHandleEvent({+ sessionId: "parent",+ hooks: first.hooks.forTrace!(traceContext("parent", "public")),+ handleEvent: async () => {},+ getAttemptScope: () => scope,+ isFrameworkTool: () => true,+ })!(+ createActionsRequestedEvent({+ actions: [action],+ sequence: 0,+ stepIndex: 0,+ turnId: "turn_0",+ }),+ );+ });+ const restored = await deserializeContext(serializeContext(ctx));+ await contextStorage.run(restored, async () => {+ await createInstrumentationHandleEvent({+ sessionId: "parent",+ hooks: second.hooks.forTrace!(traceContext("parent", "public")),+ handleEvent: async () => {},+ })!(+ createActionResultEvent({+ result: {+ callId: "review",+ kind: "tool-result",+ toolName: "reviewer",+ output: "Looks ready.",+ },+ sequence: 0,+ stepIndex: 0,+ turnId: "turn_0",+ }),+ );+ });+ const spans = second.exporter.getFinishedSpans();+ const action = spans.find((span) => span.name === "agent.action")!;+ expect(action.attributes).toMatchObject({+ "agent.action.kind": kind,+ "agent.invocation.role": "caller",+ "gen_ai.agent.name": "reviewer",+ });+ expect(+ spans.find((span) => span.name === "execute_tool reviewer")?.parentSpanContext?.spanId,+ ).toBe(action.spanContext().spanId);+ expect(+ spans.find((span) => span.name === "execute_tool reviewer")?.attributes[+ "agent.tool.is_framework"+ ],+ ).toBe(true);+ } finally {+ vi.unstubAllEnvs();+ await first.shutdown();+ await second.shutdown();+ }+ },+ );it("preserves explicit trace-session identity on every remote and local-child span", async () => {vi.stubEnv("VERCEL_ENV", "preview");const runtime = { ...createRuntime(), memoryOperations: true };diff --git a/packages/eve/src/tracing/agent-tool-instrumentation.ts b/packages/eve/src/tracing/agent-tool-instrumentation.tsindex db3b9ea10..a028cd322 100644--- a/packages/eve/src/tracing/agent-tool-instrumentation.ts+++ b/packages/eve/src/tracing/agent-tool-instrumentation.ts@@ -71,6 +71,7 @@ export function createAgentToolInstrumentation(input: {const byAttempt = new Map<string, Map<string, ToolSpanState>>();const onStarted = async (event: InstrumentationToolCallStartedEvent): Promise<void> => {+ if (byAttempt.get(event.scope.attemptId)?.has(event.idempotencyKey)) return;const actionKey = actionIdempotencyKey(event.scope.sessionId, event.scope.turnId, event.callId);const fallback = input.resolveFallback(event);let state = fallback === undefined ? undefined : reserve(event, actionKey, fallback);@@ -167,7 +168,7 @@ export function createAgentToolInstrumentation(input: {fallbackParent: parent.context,idempotencyKey: event.idempotencyKey,spanId,- startTimeMs: Date.now(),+ startTimeMs: event.startedAtMs ?? Date.now(),};state.context = withAgentToolSpanContext(state.context, {recordInputs: input.recordInputs,@@ -235,7 +236,7 @@ export function createAgentToolInstrumentation(input: {const result = contentAttribute(terminal.output.output);if (result !== undefined) span.setAttribute("gen_ai.tool.call.result", result);}- span.end();+ span.end(terminal?.completedAtMs);byAction.delete(state.actionKey);const states = byAttempt.get(state.attemptId);states?.delete(state.idempotencyKey);@@ -243,10 +244,9 @@ export function createAgentToolInstrumentation(input: {}}-function toolAttributes(- event: InstrumentationToolCallStartedEvent,-): Record<string, string | number> {+function toolAttributes(event: InstrumentationToolCallStartedEvent): Attributes {return {+ "agent.tool.is_framework": event.frameworkTool === true,...(event.scope.functionId === undefined? {}: { "gen_ai.agent.name": event.scope.functionId }),diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjsindex 540e3637d..53887f968 100644--- a/scripts/guard-invariants.mjs+++ b/scripts/guard-invariants.mjs@@ -121,6 +121,8 @@* `execution/legacy-remote-agent/`. Only the ingress files that* route protocol-1 callers into it may import it, so deleting the* directory removes protocol 1 without a search.+ * rule 49 — Provided tool definitions carry a framework tool flag,+ * so telemetry ownership survives renamed and namespaced tools.** Baselines for rules with pre-existing violations live in* `guard-invariants-baseline.json`. Counts and allowlists in that file@@ -1117,6 +1119,64 @@ async function checkRule30VendoredCompiledPackageJson() {return violations;}+// Provided definitions must carry identity, not rely on their filesystem or runtime name.+async function checkFrameworkActionIdentity() {+ const violations = [];+ const roots = ["packages/eve/src/tools/provided", "packages/eve/src/tools/framework"];+ const files = [];+ for (const root of roots) {+ for await (const file of walkFiles(join(REPO_ROOT, root))) files.push(file);+ }+ files.push({+ absPath: join(REPO_ROOT, "packages/eve/src/execution/tools/connection-tools.ts"),+ relPath: "packages/eve/src/execution/tools/connection-tools.ts",+ });+ for (const { absPath, relPath } of files) {+ if (!absPath.endsWith(".ts") || absPath.endsWith(".test.ts")) continue;+ const source = await readFile(absPath, "utf8");+ const ast = ts.createSourceFile(relPath, source, ts.ScriptTarget.Latest, true);+ const report = (node, message) =>+ violations.push({+ rule: 49,+ file: toPosix(relPath),+ line: ast.getLineAndCharacterOfPosition(node.getStart(ast)).line + 1,+ message,+ });+ const visit = (node) => {+ if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {+ const name = node.expression.text;+ if (["defineTool", "defineWorkflowTool", "stampToolDefinition"].includes(name)) {+ const parent = node.parent;+ if (+ !ts.isCallExpression(parent) ||+ !ts.isIdentifier(parent.expression) ||+ parent.expression.text !== "frameworkTool"+ )+ report(+ node,+ "Wrap provided tool definitions in frameworkTool(definition), so renamed tools remain marked in traces.",+ );+ }+ }+ if (ts.isObjectLiteralExpression(node)) {+ const properties = new Map(+ node.properties+ .filter(ts.isPropertyAssignment)+ .map((property) => [property.name.getText(ast), property.initializer]),+ );+ if (properties.has("frameworkAction")) {+ const flag = properties.get("frameworkTool");+ if (flag === undefined || flag.kind !== ts.SyntaxKind.TrueKeyword)+ report(node, "Framework harness tools must declare frameworkTool: true.");+ }+ }+ ts.forEachChild(node, visit);+ };+ visit(ast);+ }+ return violations;+}+// ---------- Rule 31: removed CLI entry points stay removed ----------const ACTIVE_CLI_REFERENCE_EXTENSIONS = /\.(?:[cm]?[jt]sx?|mdx?|json|ya?ml)$/;@@ -1658,6 +1718,7 @@ async function main() {// Rule 47violations.push(...state.rule47);violations.push(...state.rule48);+ violations.push(...(await checkFrameworkActionIdentity()));if (violations.length === 0) {process.stdout.write("[eve:guard:invariants] ok — all mechanical lints passed.\n");