Gemini CLI
从源码学会它怎么工作

   79  const MAX_TURNS = 100;
   80  
   81  type BeforeAgentHookReturn =
   82    | {
   83        type: GeminiEventType.AgentExecutionStopped;
   84        value: { reason: string; systemMessage?: string };
   85      }
   86    | {
   87        type: GeminiEventType.AgentExecutionBlocked;
   88        value: { reason: string; systemMessage?: string };
   89      }
   90    | { additionalContext: string | undefined }
   91    | undefined;
   92  
   93  export class GeminiClient {
   94    private chat?: GeminiChat;
   95    private sessionTurnCount = 0;
   96  
   97    private readonly loopDetector: LoopDetectionService;
   98    private readonly compressionService: ChatCompressionService;
   99    private readonly agentHistoryProvider: AgentHistoryProvider;
  100    private readonly toolOutputMaskingService: ToolOutputMaskingService;
  101    private contextManager?: ContextManager;
  102    private lastPromptId: string;
  103    private currentSequenceModel: string | null = null;
  104    private lastSentIdeContext: IdeContext | undefined;
  105    private forceFullIdeContext = true;
  106  
  107    /**
  108     * At any point in this conversation, was compression triggered without
  109     * being forced and did it fail?
  110     */
  111    private hasFailedCompressionAttempt = false;

  614    private async *processTurn(
  615      request: PartListUnion,
  616      signal: AbortSignal,
  617      prompt_id: string,
  618      boundedTurns: number,
  619      displayContent?: PartListUnion,
  620    ): AsyncGenerator<ServerGeminiStreamEvent, Turn> {
  621      // Re-initialize turn (it was empty before if in loop, or new instance)
  622      let turn = new Turn(this.getChat(), prompt_id);
  623  
  624      this.sessionTurnCount++;
  625      if (
  626        this.config.getMaxSessionTurns() > 0 &&
  627        this.sessionTurnCount > this.config.getMaxSessionTurns()
  628      ) {
  629        yield { type: GeminiEventType.MaxSessionTurns };
  630        return turn;
  631      }
  632  
  633      if (!boundedTurns) {
  634        return turn;
  635      }
  636  
  637      // Check for context window overflow
  638      const modelForLimitCheck = this._getActiveModelForCurrentTurn();
      … 66 lines omitted; exact range 614–715 …
  705        this.getContentGeneratorOrFail(),
  706        modelForLimitCheck,
  707      );
  708  
  709      if (estimatedRequestTokenCount > remainingTokenCount) {
  710        yield {
  711          type: GeminiEventType.ContextWindowWillOverflow,
  712          value: { estimatedRequestTokenCount, remainingTokenCount },
  713        };
  714        return turn;
  715      }

  744      // Re-initialize turn with fresh history
  745      turn = new Turn(this.getChat(), prompt_id);
  746  
  747      const loopResult = await this.loopDetector.turnStarted(signal);
  748      if (loopResult.count > 1) {
  749        yield { type: GeminiEventType.LoopDetected };
  750        return turn;
  751      } else if (loopResult.count === 1) {
  752        if (boundedTurns <= 1) {
  753          yield { type: GeminiEventType.MaxSessionTurns };
  754          return turn;
  755        }
  756        return yield* this._recoverFromLoop(
  757          loopResult,
  758          signal,
  759          prompt_id,
  760          boundedTurns,
  761          displayContent,
  762        );
  763      }

   35  
   36  /**
   37   * Interface abstracting the core functionalities for generating content and counting tokens.
   38   */
   39  export interface ContentGenerator {
   40    generateContent(
   41      request: GenerateContentParameters,
   42      userPromptId: string,
   43      role: LlmRole,
   44    ): Promise<GenerateContentResponse>;
   45  
   46    generateContentStream(
   47      request: GenerateContentParameters,
   48      userPromptId: string,
   49      role: LlmRole,
   50    ): Promise<AsyncGenerator<GenerateContentResponse>>;
   51  
   52    countTokens(request: CountTokensParameters): Promise<CountTokensResponse>;
   53  
   54    embedContent(request: EmbedContentParameters): Promise<EmbedContentResponse>;
   55  
   56    userTier?: UserTierId;
   57  
   58    userTierName?: string;
   59  
   60    paidTier?: GeminiUserTier;
   61  }
   62  
   63  export enum AuthType {
   64    LOGIN_WITH_GOOGLE = 'oauth-personal',
   65    USE_GEMINI = 'gemini-api-key',
   66    USE_VERTEX_AI = 'vertex-ai',
   67    LEGACY_CLOUD_SHELL = 'cloud-shell',
   68    COMPUTE_ADC = 'compute-default-credentials',
   69    GATEWAY = 'gateway',
   70  }

  285      if (
  286        apiKeyAuthMechanism === 'bearer' &&
  287        (config.authType === AuthType.USE_GEMINI ||
  288          config.authType === AuthType.USE_VERTEX_AI) &&
  289        config.apiKey
  290      ) {
  291        baseHeaders['Authorization'] = `Bearer ${config.apiKey}`;
  292      }
  293      if (
  294        config.authType === AuthType.LOGIN_WITH_GOOGLE ||
  295        config.authType === AuthType.COMPUTE_ADC
  296      ) {
  297        const httpOptions = { headers: baseHeaders };
  298        return new LoggingContentGenerator(
  299          new ModelMappingContentGenerator(
  300            await createCodeAssistContentGenerator(
  301              httpOptions,
  302              config.authType,
  303              gcConfig,
  304              sessionId,
  305            ),
  306            CCPA_AI_MODEL_MAPPINGS,
  307          ),
  308          gcConfig,
  309        );
  310      }

  517      const streamWithRetries = async function* (
  518        this: GeminiChat,
  519      ): AsyncGenerator<StreamEvent, void, void> {
  520        try {
  521          const maxAttempts = this.context.config.getMaxAttempts();
  522  
  523          for (let attempt = 0; attempt < maxAttempts; attempt++) {
  524            let isConnectionPhase = true;
  525            try {
  526              if (attempt > 0) {
  527                yield { type: StreamEventType.RETRY };
  528              }
  529  
  530              // If this is a retry, update the key with the new context.
  531              const currentConfigKey =
  532                attempt > 0
  533                  ? { ...modelConfigKey, isRetry: true }
  534                  : modelConfigKey;
  535  
  536              isConnectionPhase = true;
  537              const stream = await this.makeApiCallAndProcessStream(
  538                currentConfigKey,
  539                requestHistory,
  540                prompt_id,
  541                signal,
      … 26 lines omitted; exact range 517–578 …
  568                    value: error.syntheticResponse,
  569                  };
  570                }
  571                return; // Stop the generator
  572              }
  573  
  574              if (isConnectionPhase) {
  575                // Connection phase errors have already been retried by retryWithBackoff.
  576                // If they bubble up here, they are exhausted or fatal.
  577                throw error;
  578              }

  236    | ServerGeminiModelInfoEvent
  237    | ServerGeminiAgentExecutionStoppedEvent
  238    | ServerGeminiAgentExecutionBlockedEvent;
  239  
  240  // A turn manages the agentic loop turn within the server context.
  241  export class Turn {
  242    private callCounter = 0;
  243  
  244    readonly pendingToolCalls: ToolCallRequestInfo[] = [];
  245    private debugResponses: GenerateContentResponse[] = [];
  246    private pendingCitations = new Set<string>();
  247    private cachedResponseText: string | undefined = undefined;
  248    finishReason: FinishReason | undefined = undefined;
  249    private hasLoggedRagTrace = false;
  250  
  251    constructor(
  252      private readonly chat: GeminiChat,
  253      private readonly prompt_id: string,
  254    ) {}
  255  
  256    // The run method yields simpler events suitable for server logic
  257    async *run(
  258      modelConfigKey: ModelConfigKey,
  259      req: PartListUnion,
  260      signal: AbortSignal,
      … 49 lines omitted; exact range 236–320 …
  310          const resp = streamEvent.value;
  311          if (!resp) continue; // Skip if there's no response body
  312  
  313          // Log RAG trace if enabled (only once per turn to avoid log bloat on streams)
  314          if (
  315            !this.hasLoggedRagTrace &&
  316            this.chat.context.config.getLogRagSnippets?.()
  317          ) {
  318            let ragStatus: string | undefined;
  319            let snippets: RagSnippet[] | undefined;
  320  

  250        content.length === 1 &&
  251        'tool' in call &&
  252        call.tool instanceof DiscoveredMCPTool
  253      ) {
  254        const firstPart = content[0];
  255        if (typeof firstPart === 'object' && typeof firstPart.text === 'string') {
  256          const textContent = firstPart.text;
  257          const threshold = this.config.getTruncateToolOutputThreshold();
  258  
  259          if (threshold > 0 && textContent.length > threshold) {
  260            const originalContentLength = textContent.length;
  261            const { outputFile: savedPath } = await saveTruncatedToolOutput(
  262              textContent,
  263              toolName,
  264              callId,
  265              this.config.storage.getProjectTempDir(),
  266              this.context.promptId,
  267            );
  268            outputFile = savedPath;
  269            const truncatedText = formatTruncatedToolOutput(
  270              textContent,
  271              outputFile,
  272              threshold,
  273            );
  274  
      … 12 lines omitted; exact range 250–297 …
  287                threshold,
  288              }),
  289            );
  290  
  291            return { truncatedContent, outputFile };
  292          }
  293        }
  294      }
  295  
  296      return { truncatedContent: content, outputFile };
  297    }

   37  /**
   38   * Default threshold for compression token count as a fraction of the model's
   39   * token limit. If the chat history exceeds this threshold, it will be compressed.
   40   */
   41  const DEFAULT_COMPRESSION_TOKEN_THRESHOLD = 0.5;
   42  
   43  /**
   44   * The fraction of the latest chat history to keep. A value of 0.3
   45   * means that only the last 30% of the chat history will be kept after compression.
   46   */
   47  const COMPRESSION_PRESERVE_THRESHOLD = 0.3;
   48  
   49  /**
   50   * The budget for function response tokens in the preserved history.
   51   */
   52  const COMPRESSION_FUNCTION_RESPONSE_TOKEN_BUDGET = 50_000;

  124  /**
  125   * Processes the chat history to ensure function responses don't exceed a specific token budget.
  126   *
  127   * This function implements a "Reverse Token Budget" strategy:
  128   * 1. It iterates through the history from the most recent turn to the oldest.
  129   * 2. It keeps a running tally of tokens used by function responses.
  130   * 3. Recent tool outputs are preserved in full to maintain high-fidelity context for the current turn.
  131   * 4. Once the budget (COMPRESSION_FUNCTION_RESPONSE_TOKEN_BUDGET) is exceeded, any older large
  132   *    tool responses are truncated to their last 30 lines and saved to a temporary file.
  133   *
  134   * This ensures that compression effectively reduces context size even when recent turns
  135   * contain massive tool outputs (like large grep results or logs).
  136   */
  137  async function truncateHistoryToBudget(
  138    history: readonly Content[],
  139    config: Config,
  140  ): Promise<Content[]> {
  141    let functionResponseTokenCounter = 0;
  142    const truncatedHistory: Content[] = [];

  107    /**
  108     * At any point in this conversation, was compression triggered without
  109     * being forced and did it fail?
  110     */
  111    private hasFailedCompressionAttempt = false;
  112  
  113    constructor(private readonly context: AgentLoopContext) {
  114      this.loopDetector = new LoopDetectionService(this.config);
  115      this.compressionService = new ChatCompressionService();
  116      this.agentHistoryProvider = new AgentHistoryProvider(
  117        this.config.agentHistoryProviderConfig,
  118        this.config,
  119      );
  120      this.toolOutputMaskingService = new ToolOutputMaskingService();

   26  export class ContextManager {
   27    // Master state containing the pristine graph and current active graph.
   28    private buffer: ContextWorkingBufferImpl =
   29      ContextWorkingBufferImpl.initialize([]);
   30  
   31    private readonly eventBus: ContextEventBus;
   32    private readonly orchestrator: PipelineOrchestrator;
   33  
   34    // Track what IDs have been evaluated for triggers to prevent redundant processing
   35    private readonly evaluatedNodeIds = new Set<string>();
   36  
   37    // Hysteresis tracking to prevent utility call churn
   38    private lastTriggeredDeficit = 0;
   39    private lastTriggeredNormalizeDeficit = 0;
   40  
   41    // Cache for Anomaly 3 (Redundant Renders)
   42    private lastRenderCache?: {
   43      nodesHash: string;
   44      result: {
   45        history: HistoryTurn[];
   46        apiHistory: Content[];
   47        pendingApiHistory: Content[];
   48        didApplyManagement: boolean;
   49        baseUnits: number;
   50        processedNodes: readonly ConcreteNode[];
      … 27 lines omitted; exact range 26–88 …
   78          );
   79          return;
   80        }
   81  
   82        this.buffer = this.buffer.applyProcessorResult(
   83          event.processorId,
   84          event.targets,
   85          event.returnedNodes,
   86        );
   87      });
   88    }

  640      let currentBaseUnits = 0;
  641      let apiHistoryOverride: Content[] | undefined = undefined;
  642  
  643      if (this.config.getContextManagementConfig().enabled) {
  644        if (this.contextManager) {
  645          const rawPendingRequest = createUserContent(request);
  646          const pendingRequest = {
  647            id: randomUUID(),
  648            content: rawPendingRequest,
  649          };
  650          const {
  651            history: newHistory,
  652            apiHistory,
  653            pendingApiHistory,
  654            baseUnits,
  655          } = await this.contextManager.renderHistory(
  656            pendingRequest,
  657            undefined,
  658            signal,
  659          );
  660  
  661          currentBaseUnits = baseUnits;
  662  
  663          // Use the PROCESSED pending content if available (e.g. if cleaned or distilled)
  664          const finalPendingContent =
      … 3 lines omitted; exact range 640–678 …
  668  
  669          // Late-bind the prompt: Append the active request to the managed history
  670          // only for the purpose of the upcoming API call.
  671          apiHistoryOverride = [...apiHistory, finalPendingContent];
  672  
  673          this.getChat().setHistory(newHistory);
  674  
  675          // Use the original request for display/recording,
  676          // but the processed one for the API and durable history.
  677          displayContent = rawPendingRequest.parts || [];
  678          request = finalPendingContent.parts || [];

   49  function isWildcardPattern(name: string): boolean {
   50    return name === '*' || name.includes('*');
   51  }
   52  
   53  /**
   54   * Checks if a tool call matches a wildcard pattern.
   55   * Supports global (*) and the explicit MCP (*mcp_serverName_**) format.
   56   */
   57  function matchesWildcard(
   58    pattern: string,
   59    toolName: string,
   60    serverName: string | undefined,
   61  ): boolean {
   62    if (pattern === '*') {
   63      return true;
   64    }
   65  
   66    if (pattern === `${MCP_TOOL_PREFIX}*`) {
   67      return serverName !== undefined;
   68    }
   69  
   70    if (pattern.startsWith(MCP_TOOL_PREFIX) && pattern.endsWith('_*')) {
   71      const expectedServerName = pattern.slice(MCP_TOOL_PREFIX.length, -2);
   72      // 1. Must be an MCP tool call (has serverName)
   73      // 2. Server name must match
      … 111 lines omitted; exact range 49–195 …
  185    // Check interactive if specified
  186    if ('interactive' in rule && rule.interactive !== undefined) {
  187      if (rule.interactive && nonInteractive) {
  188        return false;
  189      }
  190      if (!rule.interactive && !nonInteractive) {
  191        return false;
  192      }
  193    }
  194  
  195    return true;

  253      this.nonInteractive = config.nonInteractive ?? false;
  254      this.defaultDecision =
  255        config.defaultDecision ??
  256        (this.nonInteractive ? PolicyDecision.DENY : PolicyDecision.ASK_USER);
  257      this.disableAlwaysAllow = config.disableAlwaysAllow ?? false;
  258      this.checkerRunner = checkerRunner;
  259      this.approvalMode = config.approvalMode ?? ApprovalMode.DEFAULT;
  260      this.sandboxManager = config.sandboxManager ?? new NoopSandboxManager();

   19  /**
   20   * Creates a sandbox manager based on the provided settings.
   21   */
   22  export function createSandboxManager(
   23    sandbox: SandboxConfig | undefined,
   24    options: GlobalSandboxOptions,
   25    approvalMode?: string,
   26  ): SandboxManager {
   27    if (!options.modeConfig && options.policyManager && approvalMode) {
   28      options.modeConfig = options.policyManager.getModeConfig(approvalMode);
   29    }
   30  
   31    if (sandbox?.enabled) {
   32      if (os.platform() === 'win32') {
   33        return new WindowsSandboxManager(options);
   34      } else if (os.platform() === 'linux') {
   35        return new LinuxSandboxManager(options);
   36      } else if (os.platform() === 'darwin') {
   37        return new MacOsSandboxManager(options);
   38      }
   39      return new LocalSandboxManager(options);
   40    }
   41  
   42    return new NoopSandboxManager(options);
   43  }

  194  /**
  195   * Files that represent the governance or "constitution" of the repository
  196   * and should be write-protected in any sandbox.
  197   */
  198  export const GOVERNANCE_FILES = [
  199    { path: '.gitignore', isDirectory: false },
  200    { path: '.geminiignore', isDirectory: false },
  201    { path: '.git', isDirectory: true },
  202  ] as const;
  203  
  204  /**
  205   * Files that contain sensitive secrets or credentials and should be
  206   * completely hidden (deny read/write) in any sandbox.
  207   */
  208  export const SECRET_FILES = [
  209    { pattern: '.env' },
  210    { pattern: '.env.*' },
  211  ] as const;
  212  
  213  /**
  214   * Checks if a given file name matches any of the secret file patterns.
  215   */
  216  export function isSecretFile(fileName: string): boolean {
  217    return SECRET_FILES.some((s) => {
  218      if (s.pattern.endsWith('*')) {
  219        const prefix = s.pattern.slice(0, -1);
  220        return fileName.startsWith(prefix);
  221      }
  222      return fileName === s.pattern;
  223    });

   49    private static get DEFAULT_CONFIG(): SandboxTomlSchemaType {
   50      if (!SandboxPolicyManager._DEFAULT_CONFIG) {
   51        const __filename = fileURLToPath(import.meta.url);
   52        const __dirname = path.dirname(__filename);
   53        const defaultPath = path.join(
   54          __dirname,
   55          'policies',
   56          'sandbox-default.toml',
   57        );
   58        try {
   59          const content = fs.readFileSync(defaultPath, 'utf8');
   60          if (typeof content !== 'string') {
   61            SandboxPolicyManager._DEFAULT_CONFIG = {
   62              modes: {
   63                plan: {
   64                  network: false,
   65                  readonly: true,
   66                  approvedTools: [],
   67                  allowOverrides: true,
   68                },
   69                default: {
   70                  network: false,
   71                  readonly: false,
   72                  approvedTools: [],
   73                  allowOverrides: true,
      … 10 lines omitted; exact range 49–94 …
   84            return SandboxPolicyManager._DEFAULT_CONFIG;
   85          }
   86          SandboxPolicyManager._DEFAULT_CONFIG = SandboxTomlSchema.parse(
   87            toml.parse(content),
   88          );
   89        } catch (e) {
   90          debugLogger.error(`Failed to parse default sandbox policy: ${e}`);
   91          throw new Error(`Failed to parse default sandbox policy: ${e}`);
   92        }
   93      }
   94      return SandboxPolicyManager._DEFAULT_CONFIG;

  188    async connect(): Promise<void> {
  189      if (this.status !== MCPServerStatus.DISCONNECTED) {
  190        throw new Error(
  191          `Can only connect when the client is disconnected, current state is ${this.status}`,
  192        );
  193      }
  194      this.updateStatus(MCPServerStatus.CONNECTING);
  195      try {
  196        this.client = await connectToMcpServer(
  197          this.clientVersion,
  198          this.serverName,
  199          this.serverConfig,
  200          this.debugMode,
  201          this.workspaceContext,
  202          this.cliConfig,
  203        );
  204  
  205        this.registerNotificationHandlers();
  206  
  207        const originalOnError = this.client.onerror;
  208        this.client.onerror = (error) => {
  209          if (this.status !== MCPServerStatus.CONNECTED) {
  210            return;
  211          }
  212          if (originalOnError) originalOnError(error);
      … 69 lines omitted; exact range 188–292 …
  282    }
  283  
  284    /**
  285     * Disconnects from the MCP server.
  286     */
  287    async disconnect(): Promise<void> {
  288      if (this.status !== MCPServerStatus.CONNECTED) {
  289        return;
  290      }
  291      for (const registries of this.registeredRegistries) {
  292        registries.toolRegistry.removeMcpToolsByServer(this.serverName);

   31    /**
   32     * Fully initializes all active extensions.
   33     *
   34     * Called within `Config.initialize`, which must already have an
   35     * McpClientManager, PromptRegistry, and GeminiChat set up.
   36     */
   37    async start(config: Config): Promise<void> {
   38      this.isStarting = true;
   39      try {
   40        if (!this.config) {
   41          this.config = config;
   42        } else {
   43          throw new Error('Already started, you may only call `start` once.');
   44        }
   45        await Promise.all(
   46          this.getExtensions()
   47            .filter((e) => e.isActive)
   48            .map(this.startExtension.bind(this)),
   49        );
   50      } finally {
   51        this.isStarting = false;
   52      }
   53    }
   54  
   55    /**
      … 44 lines omitted; exact range 31–110 …
  100        this.startCompletedCount++;
  101        this.eventEmitter?.emit('extensionsStarting', {
  102          total: this.startingCount,
  103          completed: this.startCompletedCount,
  104        });
  105        if (this.startingCount === this.startCompletedCount) {
  106          this.startingCount = 0;
  107          this.startCompletedCount = 0;
  108        }
  109        await this.maybeRefreshMemories();
  110      }

  383  export function getExtensionMemoryPaths(
  384    extensionLoader: ExtensionLoader,
  385  ): string[] {
  386    const extensionPaths = extensionLoader
  387      .getExtensions()
  388      .filter((ext) => ext.isActive)
  389      .flatMap((ext) => ext.contextFiles)
  390      .map((p) => toAbsolutePath(p));
  391  
  392    // Deduplicate case-insensitively (so macOS/Windows don't keep two casings of
  393    // the same file) while preserving the first encountered casing for display.
  394    const seenKeys = new Set<string>();
  395    const unique: string[] = [];
  396    for (const p of extensionPaths) {
  397      const key = normalizePath(p);
  398      if (seenKeys.has(key)) continue;
  399      seenKeys.add(key);
  400      unique.push(p);
  401    }
  402    return unique.sort();
  403  }
  404  
  405  export async function getEnvironmentMemoryPaths(
  406    trustedRoots: string[],
  407    boundaryMarkers: readonly string[] = ['.git'],
      … 36 lines omitted; exact range 383–454 …
  444        pList
  445          .map((p) => contentsMap.get(p))
  446          .filter((c): c is GeminiFileContent => !!c),
  447      );
  448  
  449    return {
  450      global: getConcatenated(paths.global),
  451      extension: getConcatenated(paths.extension),
  452      project: getConcatenated(paths.project),
  453      userProjectMemory: getConcatenated(paths.userProjectMemory ?? []),
  454    };

   17  export class SkillManager {
   18    private skills: SkillDefinition[] = [];
   19    private activeSkillNames: Set<string> = new Set();
   20    private adminSkillsEnabled = true;
   21  
   22    /**
   23     * Clears all discovered skills.
   24     */
   25    clearSkills(): void {
   26      this.skills = [];
   27    }
   28  
   29    /**
   30     * Resets session-scoped state (active skill names).
   31     */
   32    reset(): void {
   33      this.activeSkillNames.clear();
   34    }
   35  
   36    /**
   37     * Sets administrative settings for skills.
   38     */
   39    setAdminSettings(enabled: boolean): void {
   40      this.adminSkillsEnabled = enabled;
   41    }
      … 47 lines omitted; exact range 17–99 …
   89      const projectSkills = await loadSkillsFromDir(
   90        storage.getProjectSkillsDir(),
   91      );
   92      this.addSkillsWithPrecedence(projectSkills);
   93  
   94      // 4.1 Workspace agent skills alias (.agents/skills)
   95      const projectAgentSkills = await loadSkillsFromDir(
   96        storage.getProjectAgentSkillsDir(),
   97      );
   98      this.addSkillsWithPrecedence(projectAgentSkills);
   99    }

  153    // Hook state to deduplicate BeforeAgent calls and track response for
  154    // AfterAgent
  155    private hookStateMap = new Map<
  156      string,
  157      {
  158        hasFiredBeforeAgent: boolean;
  159        cumulativeResponse: string;
  160        activeCalls: number;
  161        originalRequest: PartListUnion;
  162      }
  163    >();
  164  
  165    private async fireBeforeAgentHookSafe(
  166      request: PartListUnion,
  167      prompt_id: string,
  168    ): Promise<BeforeAgentHookReturn> {
  169      let hookState = this.hookStateMap.get(prompt_id);
  170      if (!hookState) {
  171        hookState = {
  172          hasFiredBeforeAgent: false,
  173          cumulativeResponse: '',
  174          activeCalls: 0,
  175          originalRequest: request,
  176        };
  177        this.hookStateMap.set(prompt_id, hookState);
      … 64 lines omitted; exact range 153–252 …
  242      const finalRequest = hookState.originalRequest || currentRequest;
  243  
  244      const hookOutput = await this.config
  245        .getHookSystem()
  246        ?.fireAfterAgentEvent(
  247          partToString(finalRequest),
  248          finalResponseText,
  249          stopHookActive,
  250        );
  251  
  252      return hookOutput;

   14  /**
   15   * AgentSession is a wrapper around AgentProtocol that provides a more
   16   * convenient API for consuming agent activity as an AsyncIterable.
   17   */
   18  export class AgentSession implements AgentProtocol {
   19    private _protocol: AgentProtocol;
   20  
   21    constructor(protocol: AgentProtocol) {
   22      this._protocol = protocol;
   23    }
   24  
   25    async send(payload: AgentSend): Promise<{ streamId: string | null }> {
   26      return this._protocol.send(payload);
   27    }
   28  
   29    subscribe(callback: (event: AgentEvent) => void): Unsubscribe {
   30      return this._protocol.subscribe(callback);
   31    }
   32  
   33    async abort(): Promise<void> {
   34      return this._protocol.abort();
   35    }
   36  
   37    get events(): readonly AgentEvent[] {
   38      return this._protocol.events;
      … 20 lines omitted; exact range 14–69 …
   59     * Returns an AsyncIterable that yields events from the agent session,
   60     * optionally replaying events from history or reattaching to an existing stream.
   61     *
   62     * @param options Options for replaying or reattaching to the event stream.
   63     */
   64    async *stream(
   65      options: {
   66        eventId?: string;
   67        streamId?: string;
   68      } = {},
   69    ): AsyncIterable<AgentEvent> {

   69  class LocalSubagentProtocol implements AgentProtocol {
   70    private _events: AgentEvent[] = [];
   71    private _subscribers = new Set<(event: AgentEvent) => void>();
   72    private _streamId: string = randomUUID();
   73    private _eventCounter = 0;
   74    private _agentStartEmitted = false;
   75    private _agentEndEmitted = false;
   76    private _activeStreamId: string | undefined;
   77    private _abortController = new AbortController();
   78  
   79    // Result promise wiring — re-created per stream in _beginNewStream()
   80    private _resultResolve!: (output: OutputObject) => void;
   81    private _resultReject!: (err: unknown) => void;
   82    private _resultPromise: Promise<OutputObject> | undefined;
   83  
   84    // Buffered config from send({update})
   85    private _bufferedConfig: Record<string, unknown> = {};
   86  
   87    constructor(
   88      private readonly definition: LocalAgentDefinition,
   89      private readonly context: AgentLoopContext,
   90      // Required for API parity across protocol constructors (local, remote, legacy)
   91      _messageBus: MessageBus,
   92      private readonly _rawActivityCallback?: (
   93        activity: SubagentActivityEvent,
   94      ) => void,
   95    ) {}

  150    try {
  151      const fileStream = fs.createReadStream(filePath);
  152      const rl = readline.createInterface({
  153        input: fileStream,
  154        crlfDelay: Infinity,
  155      });
  156  
  157      let metadata: Partial<ConversationRecord> = {};
  158      const messagesMap = new Map<string, MessageRecord>();
  159      const messageIds: string[] = [];
  160      const messageKinds = new Map<
  161        string,
  162        { isUser: boolean; isResumable: boolean }
  163      >();
  164      let isTrackingMemoryScratchpadFreshness = false;
  165      let memoryScratchpadIsStale = false;
  166      let firstUserMessageStr: string | undefined;
  167  
  168      for await (const line of rl) {
  169        if (!line.trim()) continue;
  170        try {
  171          const record = JSON.parse(line) as unknown;
  172          if (isRewindRecord(record)) {
  173            if (isTrackingMemoryScratchpadFreshness) {
  174              memoryScratchpadIsStale = true;
      … 18 lines omitted; exact range 150–203 …
  193                if (found) idsToDelete.push(id);
  194              }
  195              if (found) {
  196                for (const id of idsToDelete) {
  197                  messagesMap.delete(id);
  198                }
  199              } else {
  200                messagesMap.clear();
  201              }
  202            }
  203          } else if (isMessageRecord(record)) {

  240    const otlpEndpoint = config.getTelemetryOtlpEndpoint();
  241    const otlpProtocol = config.getTelemetryOtlpProtocol();
  242    const telemetryTarget = config.getTelemetryTarget();
  243    const useCollector = config.getTelemetryUseCollector();
  244  
  245    const parsedEndpoint = parseOtlpEndpoint(otlpEndpoint, otlpProtocol);
  246    const telemetryOutfile = config.getTelemetryOutfile();
  247    const useOtlp = !!parsedEndpoint && !telemetryOutfile;
  248  
  249    const gcpProjectId =
  250      process.env['OTLP_GOOGLE_CLOUD_PROJECT'] ||
  251      process.env['GOOGLE_CLOUD_PROJECT'];
  252    const useDirectGcpExport =
  253      telemetryTarget === TelemetryTarget.GCP && !useCollector;
  254  
  255    let spanExporter:
  256      | OTLPTraceExporter
  257      | OTLPTraceExporterHttp
  258      | GcpTraceExporter
  259      | FileSpanExporter
  260      | ConsoleSpanExporter;
  261    let logExporter:
  262      | OTLPLogExporter
  263      | OTLPLogExporterHttp
  264      | GcpLogExporter
      … 43 lines omitted; exact range 240–318 …
  308          url: parsedEndpoint,
  309          compression: CompressionAlgorithm.GZIP,
  310        });
  311        metricReader = new PeriodicExportingMetricReader({
  312          exporter: new OTLPMetricExporter({
  313            url: parsedEndpoint,
  314            compression: CompressionAlgorithm.GZIP,
  315          }),
  316          exportIntervalMillis: 10000,
  317        });
  318      }

    1  
    2                                   Apache License
    3                             Version 2.0, January 2004
    4                          http://www.apache.org/licenses/
    5  
    6     TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
    7  
    8     1. Definitions.
    9  
   10        "License" shall mean the terms and conditions for use, reproduction,
   11        and distribution as defined by Sections 1 through 9 of this document.
   12  
   13        "Licensor" shall mean the copyright owner or entity authorized by
   14        the copyright owner that is granting the License.
   15  
   16        "Legal Entity" shall mean the union of the acting entity and all
   17        other entities that control, are controlled by, or are under common
   18        control with that entity. For the purposes of this definition,
   19        "control" means (i) the power, direct or indirect, to cause the
   20        direction or management of such entity, whether by contract or
   21        otherwise, or (ii) ownership of fifty percent (50%) or more of the
   22        outstanding shares, or (iii) beneficial ownership of such entity.
   23  
   24        "You" (or "Your") shall mean an individual or Legal Entity
   25        exercising permissions granted by this License.
   26  
   27        "Source" form shall mean the preferred form for making modifications,
   28        including but not limited to software source code, documentation