@didim365/agent-cli-core 0.1.0

package/dist/docs/ai_adapter/working_history/phase2_tradeoff_EventType/354/240/204/355/231/230_20260208.md

@@ -0,0 +1,286 @@
+# Phase 2 연기 항목 해소: EventType 전환 작업 결과서
+
+> 📅 **작업일**: 2026-02-08 📚 **Phase**: Phase 2 연기 항목 해소 🎯 **목표**:
+> GeminiEventType / ServerGeminiStreamEvent → LlmEventType / LlmEvent 전환 🔗
+> **이전 작업**:
+> [Phase2*ETC*연기작업정리\_20260208.md](./Phase2_ETC_연기작업정리_20260208.md)
+> 🔗 **관련 문서**: [phase3_handoff.md](../todolist/phase3_handoff.md),
+> [event-mapping-matrix.md](../event-mapping-matrix.md)
+
+---
+
+## 📋 작업 요약
+
+### 배경
+
+Phase 2 M2.2 (EventMapper 구현)에서 `LlmEventType` / `LlmEvent`를 신규
+도입했으나, 기존 소비자(`turn.ts`, `client.ts`, `loopDetectionService.ts`,
+`nonInteractiveCli.ts`, `useGeminiStream.ts`)가 여전히 `GeminiEventType` /
+`ServerGeminiStreamEvent`를 참조하여 Phase 3 진입 전 전환이 필요했음.
+
+### 접근 전략
+
+**점진적 전환**: Core 내부 → Core 소비자 → CLI 소비자 순서로, 파일별
+Red→Green→Refactor TDD 적용.
+
+**작업 순서**: turn.ts → client.ts → loopDetectionService.ts →
+nonInteractiveCli.ts → useGeminiStream.ts (각 파일의 소스 + 테스트 동시 전환)
+
+---
+
+## ✅ 변경 사항
+
+### 변경 파일 목록 (16 files — 초기 11 + 리뷰 후 5 + 3차 리뷰 1 중복 수정)
+
+| #   | 파일                                                      | 변경 내용                                                                                                                                            |
+| --- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `packages/core/src/core/turn.ts`                          | `run()` 메서드: `ServerGeminiStreamEvent` yield → `LlmEvent` yield, `mapFinishReason`/`mapUsageMetadata` 헬퍼 추가, `LlmFinishReason` re-export 추가 |
+| 2   | `packages/core/src/core/turn.test.ts`                     | 모든 mock event를 flat `LlmEvent` 구조로 전환 (281줄)                                                                                                |
+| 3   | `packages/core/src/core/client.ts`                        | `turnLoop()`: `ServerGeminiStreamEvent` → `LlmEvent` 이벤트 소비, enum 값 변경                                                                       |
+| 4   | `packages/core/src/core/client.test.ts`                   | mock stream events를 `LlmEvent` 구조로 전환 (132줄)                                                                                                  |
+| 5   | `packages/core/src/services/loopDetectionService.ts`      | `addAndCheck()`: `LlmEvent` 단일 시그니처로 통합, deprecated `addAndCheckLlm` 제거                                                                   |
+| 6   | `packages/core/src/services/loopDetectionService.test.ts` | interop 테스트 제거, 모든 이벤트 LlmEvent 형식으로 통일 (74줄)                                                                                       |
+| 7   | `packages/core/src/providers/gemini/geminiStream.ts`      | 타입 import 미세 조정                                                                                                                                |
+| 8   | `packages/cli/src/nonInteractiveCli.ts`                   | import `GeminiEventType` → `LlmEventType`, 이벤트 루프 flat field 접근                                                                               |
+| 9   | `packages/cli/src/nonInteractiveCli.test.ts`              | `ServerGeminiStreamEvent` → `LlmEvent`, 43개 테스트 이벤트 payload 전환 (520줄)                                                                      |
+| 10  | `packages/cli/src/ui/hooks/useGeminiStream.ts`            | import 정리, `FinishReason` 제거, 핸들러 시그니처 변경, switch문 20+ case 전환                                                                       |
+| 11  | `packages/cli/src/ui/hooks/useGeminiStream.test.tsx`      | 58개 테스트 이벤트 payload flat 구조 전환 (222줄)                                                                                                    |
+
+### 핵심 매핑 변경
+
+| Before (Gemini-specific)                                                                    | After (Provider-independent)                                                   |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `GeminiEventType.Content` / `event.value: string`                                           | `LlmEventType.TextDelta` / `event.text: string`                                |
+| `GeminiEventType.Thought` / `event.value: ThoughtSummary`                                   | `LlmEventType.ThoughtDelta` / `event.thought + event.metadata`                 |
+| `GeminiEventType.ToolCallRequest` / `event.value: ToolCallRequestInfo`                      | `LlmEventType.ToolCallRequest` / flat `callId, name, args, promptId`           |
+| `GeminiEventType.Error` / `event.value: { error }`                                          | `LlmEventType.Error` / `event.error: Error \| string`                          |
+| `GeminiEventType.Finished` / `event.value: { reason: FinishReason }`                        | `LlmEventType.Finished` / `event.finishReason: LlmFinishReason`                |
+| `GeminiEventType.AgentExecutionStopped` / `event.value: { reason }`                         | `LlmEventType.AgentStopped` / flat `reason, systemMessage, contextCleared`     |
+| `GeminiEventType.AgentExecutionBlocked` / `event.value: { reason }`                         | `LlmEventType.AgentBlocked` / flat `reason, systemMessage, contextCleared`     |
+| `GeminiEventType.ChatCompressed` / `event.value: { originalTokenCount }`                    | `LlmEventType.ChatCompressed` / `event.originalTokens, event.compressedTokens` |
+| `GeminiEventType.ContextWindowWillOverflow` / `event.value: { estimatedRequestTokenCount }` | `LlmEventType.ContextWindowOverflow` / `event.currentTokens, event.maxTokens`  |
+| `GeminiEventType.Citation` / `event.value: string`                                          | `LlmEventType.Citation` / `event.citations: LlmCitation[]`                     |
+| `GeminiEventType.ModelInfo` / `event.value: string`                                         | `LlmEventType.ModelInfo` / `event.modelName: string`                           |
+
+### handleFinishedEvent 리팩토링
+
+**Before**: Gemini `FinishReason` enum 15가지 각각에 대한 message 매핑
+**After**: `LlmFinishReason` 3가지 유의미 reason에 대한 간결한 message 매핑
+
+```typescript
+const finishReasonMessages: Partial<Record<LlmFinishReason, string>> = {
+  max_tokens: 'Response truncated due to token limits.',
+  content_filter: 'Response stopped due to content filtering.',
+  error: 'Response stopped due to an error.',
+};
+```
+
+세부 reason (`SAFETY`, `RECITATION`, `BLOCKLIST` 등)은 `turn.ts`의
+`mapFinishReason()`에서 `content_filter`로 통합 매핑됨.
+
+---
+
+## 🔍 Quality Gate 결과
+
+| 검증 항목                       | 결과                                                   |
+| ------------------------------- | ------------------------------------------------------ |
+| TypeCheck (core)                | ✅ 0 errors                                            |
+| TypeCheck (cli)                 | ✅ 0 errors                                            |
+| TypeCheck (a2a-server)          | ✅ 0 errors                                            |
+| Core tests                      | ✅ 4832 passed, 24 skipped                             |
+| CLI tests - nonInteractiveCli   | ✅ 43/43 passed                                        |
+| CLI tests - useGeminiStream     | ✅ 58/58 passed                                        |
+| CLI tests - 전체                | ✅ 4599 passed, 3 failed (기존 locale 이슈, 변경 무관) |
+| a2a-server tests                | ✅ 94/94 passed                                        |
+| 잔존 old type 참조 (CLI)        | ✅ 0건 (ui/types.ts 로컬 enum 제외)                    |
+| 잔존 old type 참조 (a2a-server) | ✅ 0건                                                 |
+| getCurrentSequenceModel 경고    | ✅ 해소 (mock 누락 수정)                               |
+
+### 기존 실패 테스트 (변경 무관)
+
+| 파일                                       | 원인                                   |
+| ------------------------------------------ | -------------------------------------- |
+| `src/commands/mcp.test.ts`                 | Korean locale에서 영문 help text 기대  |
+| `src/commands/extensions/install.test.ts`  | Korean locale에서 영문 yargs 에러 기대 |
+| `src/commands/extensions/validate.test.ts` | Korean locale에서 영문 yargs 에러 기대 |
+
+---
+
+## 📊 영향 분석
+
+### 하위 호환성
+
+- `turn.ts` re-export (`GeminiEventType`, `ServerGemini*` types): **유지됨** —
+  `@deprecated` 표시
+- Core `index.ts` re-export chain: `LlmEventType`과 `GeminiEventType` 모두
+  export
+- 외부 소비자: 기존 `GeminiEventType` import 여전히 동작 (deprecated 경고만
+  표시)
+
+### 삭제된 항목
+
+| 항목                                        | 파일                         | 사유                                                   |
+| ------------------------------------------- | ---------------------------- | ------------------------------------------------------ |
+| `addAndCheckLlm()` 메서드                   | loopDetectionService.ts      | `addAndCheck(LlmEvent)` 단일 메서드로 통합             |
+| interop 테스트                              | loopDetectionService.test.ts | deprecated 메서드 제거로 불필요                        |
+| `FinishReason` import                       | useGeminiStream.ts           | `@google/genai` 직접 의존 제거, `LlmFinishReason` 사용 |
+| `GeminiErrorEventValue` 타입 참조           | useGeminiStream.ts           | `Error \| string` 직접 사용                            |
+| `ServerGeminiChatCompressedEvent` 타입 참조 | useGeminiStream.ts           | flat field 파라미터로 대체                             |
+| `ServerGeminiFinishedEvent` 타입 참조       | useGeminiStream.ts           | `LlmFinishReason` 파라미터로 대체                      |
+
+---
+
+## 🔄 리뷰 후 추가 수정 사항
+
+> 📅 **수정일**: 2026-02-08 🔍 **트리거**: 코드 리뷰 피드백 (3건)
+
+### 리뷰 이슈 검증 결과
+
+| #   | 심각도   | 이슈                                                                        | 검증 결과                                     | 조치                 |
+| --- | -------- | --------------------------------------------------------------------------- | --------------------------------------------- | -------------------- |
+| 1   | **High** | `a2a-server/task.ts` return type `AsyncGenerator<ServerGeminiStreamEvent>`  | ✅ 확인 — TypeCheck 2 errors (lines 932, 973) | a2a-server 전체 전환 |
+| 2   | **High** | `acceptAgentMessage` runtime risk — `GeminiEventType.Content + event.value` | ✅ 확인 — 런타임 불일치                       | switch 문 전체 전환  |
+| 3   | **Low**  | `getCurrentSequenceModel is not a function` 경고                            | ✅ 확인 — mock 누락                           | mock 추가            |
+
+### 추가 변경 파일 목록 (4 source + 2 test files)
+
+| #   | 파일                                                 | 변경 내용                                                                                                                                                                                                                           |
+| --- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 12  | `packages/a2a-server/src/agent/task.ts`              | import: `GeminiEventType` → `LlmEventType`, `ServerGeminiStreamEvent` → `LlmEvent`; `acceptAgentMessage` switch 문 전체 전환 (flat field 접근); return types `AsyncGenerator<LlmEvent>`; Error 케이스 `ServerGeminiErrorEvent` 제거 |
+| 13  | `packages/a2a-server/src/agent/executor.ts`          | import: `GeminiEventType` → `LlmEventType`; `ToolCallRequest` 감지 시 flat field → `ToolCallRequestInfo` 조립                                                                                                                       |
+| 14  | `packages/a2a-server/src/agent/task.test.ts`         | import: `GeminiEventType` → `LlmEventType`; Citation/ModelInfo/Retry/InvalidStream 이벤트 + string literal 이벤트 flat 구조 전환                                                                                                    |
+| 15  | `packages/a2a-server/src/http/app.test.ts`           | import: `GeminiEventType` → `LlmEventType`; 7개 ToolCallRequest `value` wrapper 제거 + flat fields; 5개 string literal content/thought 이벤트 전환                                                                                  |
+| 16  | `packages/cli/src/ui/hooks/useGeminiStream.test.tsx` | `MockedGeminiClientClass`에 `getCurrentSequenceModel` mock 추가                                                                                                                                                                     |
+
+### a2a-server 핵심 매핑 변경
+
+| Before (a2a-server)                                                             | After                                                                                            |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `GeminiEventType.Content` / `event.value`                                       | `LlmEventType.TextDelta` / `event.text`                                                          |
+| `GeminiEventType.Thought` / `event.value` (ThoughtSummary)                      | `LlmEventType.ThoughtDelta` / `{ description: event.thought, subject: event.metadata?.subject }` |
+| `GeminiEventType.Citation` / `event.value` (string)                             | `LlmEventType.Citation` / `event.citations.map(c => c.url).join('\\n')`                          |
+| `GeminiEventType.ModelInfo` / `event.value`                                     | `LlmEventType.ModelInfo` / `event.modelName`                                                     |
+| `GeminiEventType.Error` / `ServerGeminiErrorEvent` cast                         | `LlmEventType.Error` / `event.error: Error \| string`                                            |
+| `GeminiEventType.ToolCallConfirmation` / `event.value.request.callId` + details | `LlmEventType.ToolCallConfirmation` / `event.callId` (details는 scheduler 관리)                  |
+| executor: `event.value` → `toolCallRequests.push()`                             | executor: flat field → `ToolCallRequestInfo` 조립 (`callId, name, args, prompt_id`)              |
+
+### ToolCallConfirmation 구조 변경 상세
+
+기존 `acceptAgentMessage`의 `ToolCallConfirmation` case는
+`event.value.details`를 `pendingToolConfirmationDetails` Map에 저장했으나,
+`LlmToolCallConfirmationEvent`는 `callId`와 `confirmed` 필드만 제공.
+
+**분석 결과**: `ToolCallConfirmation` 이벤트는 turn.ts/client.ts에서 yield되지
+않음 (dead code). 실제 tool confirmation 흐름은 scheduler의
+`shouldConfirmExecute` → `_schedulerToolCallsUpdate` 경로로 처리됨. 따라서 해당
+case를 `event.callId` 로깅만 수행하는 간소화된 형태로 전환.
+
+---
+
+## 💡 Lessons Learned
+
+1. **LlmTokenUsage 필수 필드**:
+   `{ promptTokens, completionTokens, totalTokens }` 모두 필수 — 테스트에서
+   `{ totalTokens: N }`만 사용하면 TypeCheck 실패
+2. **Core 패키지 rebuild 필수**: CLI 테스트가 `@google/gemini-cli-core`를
+   `dist/index.js`로 resolve → core 소스 변경 후 반드시
+   `npm run build -w @google/gemini-cli-core` 실행
+3. **flat event 구조에서 ToolCallRequestInfo 조립**: `LlmEvent`의 `promptId`
+   (camelCase) → `ToolCallRequestInfo`의 `prompt_id` (snake_case) 변환 필요
+4. **문자열 리터럴 타입 mock**: 테스트에서 `{ type: 'content' }` 같은 문자열
+   리터럴을 사용하면 새 enum 값과 불일치 — enum을 사용하도록 통일
+5. **Dead code 식별**: `acceptAgentMessage`의 `ToolCallConfirmation` case —
+   이벤트 소스(turn.ts/client.ts)에서 yield하지 않는 이벤트 처리 코드는 dead
+   code일 수 있음. 변환 시 이벤트 생성 경로를 추적하여 실제 도달 가능성을
+   확인해야 함
+6. **Mock 메서드 누락 경고**: Mock 객체에서 실제 코드가 호출하는 메서드가
+   누락되면 "is not a function" 런타임 경고 발생. Mock 생성 시 호출 대상 메서드
+   전수 확인 필요
+
+---
+
+## 🔄 2차 리뷰 검증 결과
+
+> 📅 **검증일**: 2026-02-08 🔍 **트리거**: 2차 코드 리뷰 피드백 (3건 — return
+> type 미전환 지적)
+
+### 제시된 이슈
+
+| #   | 심각도   | 이슈                                                                            | 지적 라인               |
+| --- | -------- | ------------------------------------------------------------------------------- | ----------------------- |
+| 1   | **High** | `sendCompletedToolsToLlm` return type `AsyncGenerator<ServerGeminiStreamEvent>` | task.ts:904 (원본 기준) |
+| 2   | **High** | TS2322: `LlmEvent` not assignable to `ServerGeminiStreamEvent`                  | task.ts:932 (원본 기준) |
+| 3   | **High** | 동일 TS2322                                                                     | task.ts:973 (원본 기준) |
+
+### 검증 결과: 이미 수정 완료
+
+리뷰어가 참조한 코드 스냅샷은 **커밋 `0102b2c` 이전(수정 전)** 상태. 해당
+커밋에서 `replace_all`로 `AsyncGenerator<ServerGeminiStreamEvent>` →
+`AsyncGenerator<LlmEvent>` 전환이 이미 포함됨.
+
+| 검증 항목                                  | 결과                                                                 |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| `ServerGeminiStreamEvent` 잔존 (task.ts)   | ✅ **0건** — `grep` 확인                                             |
+| `AsyncGenerator<LlmEvent>` 선언 위치       | line 908 (`sendCompletedToolsToLlm`), line 946 (`acceptUserMessage`) |
+| `tsc --noEmit -p a2a-server/tsconfig.json` | ✅ **0 errors**                                                      |
+| 라인 번호 차이                             | import 블록 변경(-1 line)으로 원본 904→908, 932→937, 973→978 shift   |
+
+**결론**: 3건 모두 코드 변경 및 typecheck 통과 상태이며, 문서 기술("a2a-server
+typecheck ✅ 0 errors")과 일치함. 추가 수정 불필요.
+
+---
+
+## 📌 잔여 사항
+
+| 항목                                   | 상태    | 비고                                       |
+| -------------------------------------- | ------- | ------------------------------------------ |
+| `ui/types.ts`의 로컬 `GeminiEventType` | ⏸️ 유지 | UI 상태 관리용 로컬 enum, core enum과 무관 |
+| `turn.ts` @deprecated re-exports       | ⏸️ 유지 | Phase 3에서 제거 예정                      |
+| `core/index.ts` dual export            | ⏸️ 유지 | 하위 호환 보장, Phase 3 최종 정리 시 제거  |
+
+---
+
+## 🔄 3차 리뷰 반영 — Low 이슈 수정
+
+### Low #1: `listen EPERM` (a2a-server HTTP E2E tests)
+
+- **파일**: `packages/a2a-server/src/http/app.test.ts:111`
+- **현상**: `listen EPERM: operation not permitted` — 테스트에서 실제 포트
+  바인딩 시도
+- **원인**: macOS Seatbelt sandbox 환경의 포트 바인딩 제한 (코드 회귀 아님)
+- **조치**: 코드 수정 불필요 — sandbox 미적용 환경에서 정상 동작 확인 필요
+
+### Low #2: `config.getContentGenerator is not a function` (useGeminiStream tests)
+
+- **파일**: `packages/cli/src/ui/hooks/useGeminiStream.test.tsx`
+- **현상**: 58/58 테스트 통과했으나 7건의 경고 반복 출력
+- **원인 경로**: `useGeminiStream` → tool call recording →
+  `code_assist/telemetry.ts:recordToolCallInteractions()` →
+  `getCodeAssistServer(config)` → `config.getContentGenerator()` — mockConfig에
+  해당 메서드 미존재
+- **수정**: `mockConfig`에
+  `getContentGenerator: vi.fn().mockReturnValue(undefined)` 추가
+- **결과**: 경고 0건, 58/58 테스트 통과 ✅
+
+### Low #3: `MaxListenersExceededWarning` (useGeminiStream tests)
+
+- **파일**: `packages/cli/src/ui/hooks/useGeminiStream.test.tsx`
+- **현상**:
+  `Possible EventEmitter memory leak detected. 11 retry-attempt listeners added to [CoreEventEmitter]`
+- **원인**: `coreEvents`는 모듈 레벨 싱글톤이며, 각 테스트에서 `renderHook` →
+  `useEffect` → `coreEvents.on(CoreEvent.RetryAttempt, ...)` 호출.
+  `afterEach`에서 cleanup이 없어 React의 `useEffect` cleanup
+  (`coreEvents.off`)이 실행되지 않고 리스너 누적
+- **수정**:
+  `afterEach(() => { coreEvents.removeAllListeners(CoreEvent.RetryAttempt); })`
+  추가 + `afterEach` import 추가
+- **결과**: 경고 0건, 58/58 테스트 통과 ✅
+
+### Lessons Learned
+
+7. **Mock 정합성 검증**: 테스트 통과만으로 mock 완전성을 판단하면 안 됨.
+   try-catch로 감싸진 호출 경로에서 경고가 발생할 수 있으므로, 테스트 실행 시
+   콘솔 경고/에러 출력도 반드시 확인
+8. **싱글톤 EventEmitter 리스너 누적**: 모듈 레벨 싱글톤 EventEmitter에 대해
+   `useEffect`로 리스너를 등록하는 테스트는 반드시 `afterEach`에서 리스너를
+   제거해야 함. React cleanup은 테스트 환경에서 보장되지 않을 수 있음

package/dist/docs/api/index.md

@@ -0,0 +1,5 @@
+# API Reference
+
+## Multi-Provider API
+
+- [Provider Adapter API](./providers.md)

package/dist/docs/api/providers.md

@@ -0,0 +1,56 @@
+# Provider Adapter API
+
+This page summarizes the provider-independent adapter contract used by the
+multi-provider runtime.
+
+## Core Interface
+
+All adapters implement:
+
+- `providerName: string`
+- `capabilities: LlmProviderCapabilities`
+- `generateContent(request, userPromptId, options?)`
+- `generateContentStream(request, userPromptId, options?)`
+- `countTokens(request)` (optional by capability)
+- `embedContent(request)` (optional by capability)
+
+## Request and Response Types
+
+Main request type:
+
+- `LlmGenerateRequest`
+  - `model`
+  - `messages`
+  - optional: `systemInstruction`, `tools`, `toolChoice`, sampling options
+
+Main response type:
+
+- `LlmGenerateResponse`
+  - `id`, `content`, `model`, `stopReason`
+  - optional `usage`
+
+Streaming:
+
+- `LlmEventStream` (`AsyncGenerator<LlmEvent, void, unknown>`)
+- Event enum: `LlmEventType`
+
+## Adapter Registry and Factory
+
+Runtime creation flow:
+
+1. Provider bootstrap registers factories into `ProviderRegistry`.
+2. `ProviderFactory.create(provider, config)` returns the adapter.
+3. Legacy generator wrapper exposes `llm*` methods for non-Gemini providers.
+
+## Provider Notes
+
+- Gemini: supports legacy and `llm*` paths.
+- Claude/OpenAI/OpenAI-compatible: intended for `llm*` path.
+- OpenAI-compatible runtime config:
+  - `LLM_PROVIDER=openai-compatible`
+  - `LLM_BASE_URL=<openai-compatible-endpoint>`
+  - `LLM_API_KEY` optional (gateway dependent)
+  - `LLM_API_KEY_HEADER` optional (custom auth header name)
+- OpenAI-compatible default capability profile:
+  - streaming/tool calls enabled
+  - image input, embedding, token count disabled by default

package/dist/docs/architecture.md

@@ -0,0 +1,80 @@
+# Gemini CLI Architecture Overview
+
+This document provides a high-level overview of the Gemini CLI's architecture.
+
+## Core components
+
+The Gemini CLI is primarily composed of two main packages, along with a suite of
+tools that can be used by the system in the course of handling command-line
+input:
+
+1.  **CLI package (`packages/cli`):**
+    - **Purpose:** This contains the user-facing portion of the Gemini CLI, such
+      as handling the initial user input, presenting the final output, and
+      managing the overall user experience.
+    - **Key functions contained in the package:**
+      - [Input processing](/docs/cli/commands)
+      - History management
+      - Display rendering
+      - [Theme and UI customization](/docs/cli/themes)
+      - [CLI configuration settings](/docs/get-started/configuration)
+
+2.  **Core package (`packages/core`):**
+    - **Purpose:** This acts as the backend for the Gemini CLI. It receives
+      requests sent from `packages/cli`, orchestrates interactions with the
+      Gemini API, and manages the execution of available tools.
+    - **Key functions contained in the package:**
+      - API client for communicating with the Google Gemini API
+      - Prompt construction and management
+      - Tool registration and execution logic
+      - State management for conversations or sessions
+      - Server-side configuration
+
+3.  **Tools (`packages/core/src/tools/`):**
+    - **Purpose:** These are individual modules that extend the capabilities of
+      the Gemini model, allowing it to interact with the local environment
+      (e.g., file system, shell commands, web fetching).
+    - **Interaction:** `packages/core` invokes these tools based on requests
+      from the Gemini model.
+
+## Interaction flow
+
+A typical interaction with the Gemini CLI follows this flow:
+
+1.  **User input:** The user types a prompt or command into the terminal, which
+    is managed by `packages/cli`.
+2.  **Request to core:** `packages/cli` sends the user's input to
+    `packages/core`.
+3.  **Request processed:** The core package:
+    - Constructs an appropriate prompt for the Gemini API, possibly including
+      conversation history and available tool definitions.
+    - Sends the prompt to the Gemini API.
+4.  **Gemini API response:** The Gemini API processes the prompt and returns a
+    response. This response might be a direct answer or a request to use one of
+    the available tools.
+5.  **Tool execution (if applicable):**
+    - When the Gemini API requests a tool, the core package prepares to execute
+      it.
+    - If the requested tool can modify the file system or execute shell
+      commands, the user is first given details of the tool and its arguments,
+      and the user must approve the execution.
+    - Read-only operations, such as reading files, might not require explicit
+      user confirmation to proceed.
+    - Once confirmed, or if confirmation is not required, the core package
+      executes the relevant action within the relevant tool, and the result is
+      sent back to the Gemini API by the core package.
+    - The Gemini API processes the tool result and generates a final response.
+6.  **Response to CLI:** The core package sends the final response back to the
+    CLI package.
+7.  **Display to user:** The CLI package formats and displays the response to
+    the user in the terminal.
+
+## Key design principles
+
+- **Modularity:** Separating the CLI (frontend) from the Core (backend) allows
+  for independent development and potential future extensions (e.g., different
+  frontends for the same backend).
+- **Extensibility:** The tool system is designed to be extensible, allowing new
+  capabilities to be added.
+- **User experience:** The CLI focuses on providing a rich and interactive
+  terminal experience.