[Agent Builder] expose tool call context via handler (elastic#267743)

## Summary

Add a new `callContext` property to tool handler context to expose the
following info:
- tool id
- tool call id
- call source (`user`/`agent`/`mcp`)

Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

Author: pgayvallet

x-pack/platform/packages/shared/agent-builder/agent-builder-server/tools/handler.ts

@@ -25,8 +25,9 @@ import type {
   RunContext,
 } from '../runner';
 import type { IToolFileStore } from '../runner/filestore';
-import type { AttachmentStateManager } from '../attachments';
 import type { SkillsService } from '../runner/skills_service';
+import type { ToolCallSource } from '../runner/runner';
+import type { AttachmentStateManager } from '../attachments';
 
 /**
  * Tool result as returned by the tool handler.
@@ -74,11 +75,21 @@ export type ToolHandlerFn<
   TResult extends ToolResult = ToolResult
 > = (args: TParams, context: ToolHandlerContext) => MaybePromise<ToolHandlerReturn<TResult>>;
 
+export interface ToolHandlerCallContext {
+  toolId: string;
+  toolCallId: string;
+  callSource: ToolCallSource;
+}
+
 /**
  * Scoped context which can be used during tool execution to access
  * a panel of built-in services, such as a pre-scoped elasticsearch client.
  */
 export interface ToolHandlerContext {
+  /**
+   * Information about the tool call
+   */
+  callContext: ToolHandlerCallContext;
   /**
    * The request that was provided when initiating that tool execution.
    * Can be used to create scoped services not directly exposed by this context.

x-pack/platform/packages/shared/agent-builder/agent-builder-server/tools/index.ts

@@ -23,6 +23,7 @@ export {
   type ToolHandlerFn,
   type ToolHandlerReturn,
   type ToolHandlerContext,
+  type ToolHandlerCallContext,
   type ToolHandlerResult,
   type ToolHandlerPromptReturn,
   type ToolHandlerStandardReturn,

x-pack/platform/plugins/shared/agent_builder/server/services/execution/runner/run_tool.ts

@@ -29,7 +29,10 @@ import type {
 } from '@kbn/agent-builder-server/runner';
 import { generateFakeToolCallId } from '@kbn/agent-builder-genai-utils/langchain';
 import { createErrorResult } from '@kbn/agent-builder-server';
-import type { InternalToolDefinition } from '@kbn/agent-builder-server/tools';
+import type {
+  InternalToolDefinition,
+  ToolHandlerCallContext,
+} from '@kbn/agent-builder-server/tools';
 import { isToolHandlerStandardReturn } from '@kbn/agent-builder-server/tools';
 import { getToolResultId } from '@kbn/agent-builder-server/tools';
 import { ConfirmationStatus } from '@kbn/agent-builder-common/agents';
@@ -152,9 +155,11 @@ export const runInternalTool = async <TParams = Record<string, unknown>>({
   const startTime = Date.now();
   const toolHandlerContext = await createToolHandlerContext<TParams>({
     toolExecutionParams: {
-      ...toolExecutionParams,
       toolId: tool.id,
+      toolCallId,
+      source,
       toolParams: toolParams as TParams,
+      onEvent: toolExecutionParams.onEvent ?? (() => undefined),
     },
     manager,
   });
@@ -248,14 +253,19 @@ export const runInternalTool = async <TParams = Record<string, unknown>>({
   return runToolReturn;
 };
 
+type ToolHandlerExecutionParams<TParams = Record<string, unknown>> = Pick<
+  Required<ScopedRunnerRunToolsParams<TParams>>,
+  'onEvent' | 'toolId' | 'toolCallId' | 'toolParams' | 'source'
+>;
+
 export const createToolHandlerContext = async <TParams = Record<string, unknown>>({
   manager,
   toolExecutionParams,
 }: {
-  toolExecutionParams: ScopedRunnerRunToolsParams<TParams>;
+  toolExecutionParams: ToolHandlerExecutionParams<TParams>;
   manager: RunnerManager;
 }): Promise<ToolHandlerContext> => {
-  const { onEvent, toolId, toolCallId, toolParams } = toolExecutionParams;
+  const { onEvent, toolId, toolCallId, toolParams, source } = toolExecutionParams;
   const {
     request,
     elasticsearch,
@@ -273,7 +283,15 @@ export const createToolHandlerContext = async <TParams = Record<string, unknown>
     toolManager,
   } = manager.deps;
   const spaceId = getCurrentSpaceId({ request, spaces });
+
+  const callContext: ToolHandlerCallContext = {
+    toolId,
+    toolCallId,
+    callSource: source,
+  };
+
   return {
+    callContext,
     request,
     spaceId,
     logger,

x-pack/platform/plugins/shared/agent_builder/server/test_utils/runner.ts

@@ -337,6 +337,11 @@ export interface ToolHandlerContextMock extends ToolHandlerContext {
 
 export const createToolHandlerContextMock = (): ToolHandlerContextMock => {
   return {
+    callContext: {
+      toolId: 'toolId',
+      toolCallId: 'toolCallId',
+      callSource: 'agent',
+    },
     request: httpServerMock.createKibanaRequest(),
     spaceId: 'default',
     esClient: elasticsearchServiceMock.createScopedClusterClient(),