docs: add TSDoc for agent_transfer, tool_filter, context_compactor, content_request, and agent_registry_mcp processors

core/src/agents/processors/agent_transfer_llm_request_processor.ts

@@ -14,6 +14,13 @@ import {InvocationContext} from '../invocation_context.js';
 import {isLlmAgent, LlmAgent} from '../llm_agent.js';
 import {BaseLlmRequestProcessor} from './base_llm_processor.js';
 
+/**
+ * Augments the {@link LlmRequest} to support agent transfer. When the current
+ * agent has reachable transfer targets (sub-agents, peer agents, or a parent
+ * agent), this processor registers a `transfer_to_agent` function tool and
+ * appends instructions describing each candidate so the model can choose to
+ * hand off control.
+ */
 export class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor {
   private readonly toolName = 'transfer_to_agent' as const;
   private readonly tool = new FunctionTool({
@@ -32,6 +39,13 @@ export class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor {
     },
   });
 
+  /**
+   * Appends transfer instructions and registers the `transfer_to_agent` tool
+   * when the agent has reachable transfer targets.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request to augment with transfer instructions and the transfer tool.
+   */
   // eslint-disable-next-line require-yield
   override async *runAsync(
     invocationContext: InvocationContext,

core/src/agents/processors/content_request_processor.ts

@@ -15,7 +15,23 @@ import {
   getCurrentTurnContents,
 } from './content_processor_utils.js';
 
+/**
+ * Populates {@link LlmRequest.contents} from the session event history.
+ *
+ * When a {@link CompactedEvent} exists in the session, only the most recent
+ * compacted event and the raw events that follow it are included, eliding
+ * earlier history. The extent of context included depends on the agent's
+ * `includeContents` setting: `'default'` sends the full visible history while
+ * any other value sends only the current-turn context.
+ */
 export class ContentRequestProcessor implements BaseLlmRequestProcessor {
+  /**
+   * Fills {@link LlmRequest.contents} based on the session event history and
+   * agent configuration.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request whose contents field will be populated.
+   */
   // eslint-disable-next-line require-yield
   async *runAsync(
     invocationContext: InvocationContext,

core/src/agents/processors/context_compactor_request_processor.ts

@@ -21,10 +21,22 @@ import {BaseLlmRequestProcessor} from './base_llm_processor.js';
 export class ContextCompactorRequestProcessor implements BaseLlmRequestProcessor {
   private compactors: BaseContextCompactor[];
 
+  /**
+   * @param compactors - Ordered list of compactors to evaluate; the first one
+   *   that reports it should compact will perform the compaction.
+   */
   constructor(compactors: BaseContextCompactor[]) {
     this.compactors = compactors;
   }
 
+  /**
+   * Evaluates compactors in priority order. The first compactor that indicates
+   * it should compact will compact the session history, fire plugin hooks, and
+   * yield any newly generated events. Iteration stops after one compaction.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param _llmRequest - Unused; present to satisfy the {@link BaseLlmRequestProcessor} interface.
+   */
   async *runAsync(
     invocationContext: InvocationContext,
     _llmRequest: LlmRequest,

core/src/agents/processors/tool_filter_request_processor.ts

@@ -13,8 +13,19 @@ import {isLlmAgent} from '../llm_agent.js';
 import {ReadonlyContext} from '../readonly_context.js';
 import {BaseLlmRequestProcessor} from './base_llm_processor.js';
 
+/**
+ * Filters the set of tools on the {@link LlmRequest} by delegating to the
+ * active plugin manager's `beforeToolSelection` hook. If no plugin restricts
+ * the tool set, the request is left unchanged.
+ */
 export class ToolFilterRequestProcessor extends BaseLlmRequestProcessor {
-  /** Filters the set of tools on the request based on plugins. */
+  /**
+   * Invokes plugin-based tool filtering and updates {@link LlmRequest.allowedTools}
+   * with the reduced tool set if any plugin returns a filtered result.
+   *
+   * @param invocationContext - The current invocation context.
+   * @param llmRequest - The request whose allowed tools may be restricted.
+   */
   // eslint-disable-next-line require-yield
   override async *runAsync(
     invocationContext: InvocationContext,

core/src/integrations/agent_registry/agent_registry_mcp_toolset.ts

@@ -36,6 +36,19 @@ export class AgentRegistrySingleMCPToolset extends BaseToolset {
   readonly authScheme?: AuthScheme;
   readonly authCredential?: AuthCredential;
 
+  /**
+   * @param options - Configuration for the MCP toolset.
+   * @param options.destinationResourceId - Telemetry identifier injected as
+   *   `gcp.mcp.server.destination.id` into each resolved tool's custom metadata.
+   * @param options.connectionParams - HTTP connection parameters for the MCP server.
+   * @param options.toolFilter - Optional predicate or list of tool names to include.
+   *   When omitted, all tools from the server are returned.
+   * @param options.prefix - Optional prefix prepended to each tool name (e.g. `myServer_toolName`).
+   * @param options.headerProvider - Optional async function called immediately before each
+   *   {@link getTools} invocation to supply or refresh request headers (e.g. GCP auth tokens).
+   * @param options.authScheme - Optional auth scheme forwarded to each resolved tool.
+   * @param options.authCredential - Optional credential forwarded to each resolved tool.
+   */
   constructor(options: {
     destinationResourceId?: string;
     connectionParams: StreamableHTTPConnectionParams;
@@ -56,8 +69,14 @@ export class AgentRegistrySingleMCPToolset extends BaseToolset {
   }
 
   /**
-   * Connects to the underlying MCP server, retrieves tool definitions, prefixes tool names,
-   * and injects destination telemetry metadata.
+   * Connects to the underlying MCP server, retrieves tool definitions, prefixes
+   * tool names, and injects destination telemetry metadata into each tool.
+   *
+   * The `headerProvider`, if configured, is invoked immediately before the
+   * connection is established so that tokens are always fresh.
+   *
+   * @param context - Optional readonly agent context passed to the header provider.
+   * @returns The resolved and optionally filtered list of {@link MCPTool} instances.
    */
   async getTools(context?: ReadonlyContext): Promise<BaseTool[]> {
     const headers: Record<string, string> = {};