@didim365/agent-cli-core 0.1.0

package/dist/docs/configuration.md

@@ -0,0 +1,108 @@
+# Multi-Provider Configuration
+
+This page documents environment variables for provider selection and routing.
+
+## Core Flags
+
+| Variable                | Required                      | Description                                          |
+| ----------------------- | ----------------------------- | ---------------------------------------------------- |
+| `ENABLE_MULTI_PROVIDER` | Yes (for multi-provider mode) | Enables provider routing in `createContentGenerator` |
+| `LLM_PROVIDER`          | Recommended                   | Explicit provider selection                          |
+| `LLM_MODEL`             | Optional                      | Provider model override for non-Gemini providers     |
+
+`LLM_PROVIDER` supported values:
+
+- `gemini`
+- `claude` or `anthropic`
+- `openai`
+- `openai-compatible` or `openai_compatible`
+- `didim`
+
+## Provider Credentials
+
+| Provider          | Required env                                        |
+| ----------------- | --------------------------------------------------- |
+| Gemini            | `GEMINI_API_KEY` or `GOOGLE_API_KEY`                |
+| Claude            | `ANTHROPIC_API_KEY`                                 |
+| OpenAI            | `OPENAI_API_KEY`                                    |
+| OpenAI-compatible | `LLM_BASE_URL` (required), `LLM_API_KEY` (optional) |
+| Didim             | `DIDIM_API_KEY`                                     |
+
+## OpenAI-Compatible Header Options
+
+For OpenAI-compatible endpoints, you can customize outbound headers:
+
+| Variable             | Description                              |
+| -------------------- | ---------------------------------------- |
+| `LLM_CUSTOM_HEADERS` | JSON object merged into default headers  |
+| `LLM_API_KEY_HEADER` | Custom header name for API key injection |
+
+Example:
+
+```bash
+export LLM_PROVIDER=openai-compatible
+export LLM_BASE_URL="http://localhost:8000/v1"
+export LLM_API_KEY="my-secret"
+export LLM_API_KEY_HEADER="X-API-Key"
+export LLM_CUSTOM_HEADERS='{"X-Tenant":"dev"}'
+```
+
+When `LLM_API_KEY_HEADER` is set, the OpenAI SDK `Authorization` header is
+suppressed and the key is sent via the custom header.
+
+## Selection and Precedence
+
+Provider selection precedence:
+
+1. `LLM_PROVIDER`
+2. `authType` (Gemini-only path)
+3. Gemini key fallback (`GEMINI_API_KEY` or `GOOGLE_API_KEY`)
+
+Model resolution precedence (non-Gemini providers):
+
+1. If configured model is already non-Gemini, keep it.
+2. `LLM_MODEL` override.
+3. Provider default model (`claude-sonnet-4-20250514`, `gpt-4o`, `default`).
+
+## Notes
+
+- For vLLM and similar gateways, use `openai-compatible` with `LLM_BASE_URL` and
+  a served model name.
+
+## vLLM / OpenAI-Compatible Details
+
+### `LLM_BASE_URL` format
+
+- Set the full API base URL that exposes OpenAI-compatible routes.
+- Most vLLM deployments use: `http://<host>:<port>/v1`
+
+Examples:
+
+```bash
+export LLM_BASE_URL="http://localhost:8000/v1"
+export LLM_BASE_URL="https://vllm.company.internal/v1"
+```
+
+### Recommended variables for vLLM
+
+```bash
+export ENABLE_MULTI_PROVIDER=true
+export LLM_PROVIDER=openai-compatible
+export LLM_BASE_URL="http://localhost:8000/v1"
+export LLM_MODEL="Qwen/Qwen2.5-7B-Instruct"
+```
+
+Optional auth variables:
+
+```bash
+export LLM_API_KEY="optional-or-required-by-gateway"
+export LLM_API_KEY_HEADER="X-API-Key"
+export LLM_CUSTOM_HEADERS='{"X-Tenant":"dev"}'
+```
+
+### Runtime notes
+
+- `LLM_MODEL` is useful when the configured model is Gemini-specific (`auto`,
+  `pro`, `flash`, `gemini-*`).
+- If `LLM_MODEL` is not set and a Gemini-specific model is configured, the
+  runtime resolves to `default` for `openai-compatible`.

package/dist/docs/core/index.md

@@ -0,0 +1,105 @@
+# Gemini CLI core
+
+Gemini CLI's core package (`packages/core`) is the backend portion of Gemini
+CLI, handling communication with the Gemini API, managing tools, and processing
+requests sent from `packages/cli`. For a general overview of Gemini CLI, see the
+[main documentation page](../index.md).
+
+## Navigating this section
+
+- **[Core tools API](./tools-api.md):** Information on how tools are defined,
+  registered, and used by the core.
+- **[Memory Import Processor](./memport.md):** Documentation for the modular
+  GEMINI.md import feature using @file.md syntax.
+- **[Policy Engine](./policy-engine.md):** Use the Policy Engine for
+  fine-grained control over tool execution.
+
+## Role of the core
+
+While the `packages/cli` portion of Gemini CLI provides the user interface,
+`packages/core` is responsible for:
+
+- **Gemini API interaction:** Securely communicating with the Google Gemini API,
+  sending user prompts, and receiving model responses.
+- **Prompt engineering:** Constructing effective prompts for the Gemini model,
+  potentially incorporating conversation history, tool definitions, and
+  instructional context from `GEMINI.md` files.
+- **Tool management & orchestration:**
+  - Registering available tools (e.g., file system tools, shell command
+    execution).
+  - Interpreting tool use requests from the Gemini model.
+  - Executing the requested tools with the provided arguments.
+  - Returning tool execution results to the Gemini model for further processing.
+- **Session and state management:** Keeping track of the conversation state,
+  including history and any relevant context required for coherent interactions.
+- **Configuration:** Managing core-specific configurations, such as API key
+  access, model selection, and tool settings.
+
+## Security considerations
+
+The core plays a vital role in security:
+
+- **API key management:** It handles the `GEMINI_API_KEY` and ensures it's used
+  securely when communicating with the Gemini API.
+- **Tool execution:** When tools interact with the local system (e.g.,
+  `run_shell_command`), the core (and its underlying tool implementations) must
+  do so with appropriate caution, often involving sandboxing mechanisms to
+  prevent unintended modifications.
+
+## Chat history compression
+
+To ensure that long conversations don't exceed the token limits of the Gemini
+model, the core includes a chat history compression feature.
+
+When a conversation approaches the token limit for the configured model, the
+core automatically compresses the conversation history before sending it to the
+model. This compression is designed to be lossless in terms of the information
+conveyed, but it reduces the overall number of tokens used.
+
+You can find the token limits for each model in the
+[Google AI documentation](https://ai.google.dev/gemini-api/docs/models).
+
+## Model fallback
+
+Gemini CLI includes a model fallback mechanism to ensure that you can continue
+to use the CLI even if the default "pro" model is rate-limited.
+
+If you are using the default "pro" model and the CLI detects that you are being
+rate-limited, it automatically switches to the "flash" model for the current
+session. This allows you to continue working without interruption.
+
+Internal utility calls that use `gemini-2.5-flash-lite` (for example, prompt
+completion and classification) silently fall back to `gemini-2.5-flash` and
+`gemini-2.5-pro` when quota is exhausted, without changing the configured model.
+
+## File discovery service
+
+The file discovery service is responsible for finding files in the project that
+are relevant to the current context. It is used by the `@` command and other
+tools that need to access files.
+
+## Memory discovery service
+
+The memory discovery service is responsible for finding and loading the
+`GEMINI.md` files that provide context to the model. It searches for these files
+in a hierarchical manner, starting from the current working directory and moving
+up to the project root and the user's home directory. It also searches in
+subdirectories.
+
+This allows you to have global, project-level, and component-level context
+files, which are all combined to provide the model with the most relevant
+information.
+
+You can use the [`/memory` command](../cli/commands.md) to `show`, `add`, and
+`refresh` the content of loaded `GEMINI.md` files.
+
+## Citations
+
+When Gemini finds it is reciting text from a source it appends the citation to
+the output. It is enabled by default but can be disabled with the
+ui.showCitations setting.
+
+- When proposing an edit the citations display before giving the user the option
+  to accept.
+- Citations are always shown at the end of the model’s turn.
+- We deduplicate citations and display them in alphabetical order.

package/dist/docs/core/long-term-memory-design.md

@@ -0,0 +1,254 @@
+# Long-Term Memory (PostgreSQL) Technical Design
+
+## 1. 문제 정의
+
+운영관리(SE) 업무에서는 과거 작업 이력(장애 대응, 변경 수행, 실패/재시도, 도구
+실행 결과)을 재검색해 현재 작업 의사결정에 반영해야 한다.
+
+현재 저장소의 기본 기능은 세션 재개에는 충분하지만, 중앙 검색 가능한 장기
+메모리로 쓰기에는 제한이 있다.
+
+- 기록 저장이 로컬 파일 중심
+- 질의형 검색 API 부재
+- 장기 보존/거버넌스 정책을 중앙에서 통제하기 어려움
+
+## 2. 요구사항
+
+### 기능 요구사항
+
+1. 모든 세션/메시지/도구 실행 기록을 중앙 저장소(PostgreSQL)에 저장
+2. 질의 시 과거 이력을 검색해 현재 턴 컨텍스트에 주입
+3. 프로젝트/세션/기간/태그 단위 검색 및 감사 가능
+4. 기존 로컬 세션 파일을 DB로 백필 가능
+
+### 비기능 요구사항
+
+1. 적재는 idempotent 해야 함
+2. 검색 지연 p95 300ms 이내(일반 필터 조건)
+3. DB 장애 시 CLI 본작업은 계속 진행(강건성 우선)
+4. 민감정보 마스킹/삭제정책/접근통제 제공
+
+## 3. 적용 전략
+
+## 3.1 Phase A: Hook 기반(빠른 배포)
+
+- `SessionEnd` 훅: `transcript_path` JSON를 파싱해 PostgreSQL upsert
+- `BeforeAgent` 훅: 사용자 prompt + 메타데이터로 검색 후 `additionalContext`
+  주입
+- `AfterTool` 훅(옵션): `run_shell_command`, `web_fetch`, MCP 도구 결과를 별도
+  이벤트로 저장
+
+장점:
+
+- 코어 대규모 변경 없이 빠르게 검증 가능
+
+## 3.2 Phase B: Core 내장(정식)
+
+- 코어 서비스로 적재/검색 로직 통합
+- 설정/정책/관측성/테스트를 단일 경로로 표준화
+
+## 4. 데이터 모델 (PostgreSQL + pgvector)
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE ltm_sessions (
+  session_id        text PRIMARY KEY,
+  project_hash      text NOT NULL,
+  workspace_root    text,
+  started_at        timestamptz NOT NULL,
+  ended_at          timestamptz,
+  summary           text,
+  source            text NOT NULL DEFAULT 'gemini-cli',
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE ltm_messages (
+  message_id        text PRIMARY KEY,
+  session_id        text NOT NULL REFERENCES ltm_sessions(session_id) ON DELETE CASCADE,
+  role              text NOT NULL, -- user|gemini|info|error|warning
+  ts                timestamptz NOT NULL,
+  content_text      text,
+  content_json      jsonb NOT NULL,
+  token_input       integer,
+  token_output      integer,
+  token_total       integer,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE ltm_tool_calls (
+  tool_call_id      text PRIMARY KEY,
+  session_id        text NOT NULL REFERENCES ltm_sessions(session_id) ON DELETE CASCADE,
+  message_id        text REFERENCES ltm_messages(message_id) ON DELETE SET NULL,
+  tool_name         text NOT NULL,
+  status            text NOT NULL, -- success|error|blocked
+  args_json         jsonb,
+  result_json       jsonb,
+  ts                timestamptz NOT NULL,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE ltm_chunks (
+  chunk_id          bigserial PRIMARY KEY,
+  session_id        text NOT NULL REFERENCES ltm_sessions(session_id) ON DELETE CASCADE,
+  message_id        text REFERENCES ltm_messages(message_id) ON DELETE SET NULL,
+  chunk_text        text NOT NULL,
+  embedding         vector(1536),
+  metadata          jsonb NOT NULL DEFAULT '{}'::jsonb,
+  ts                timestamptz NOT NULL,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_ltm_sessions_project_started
+  ON ltm_sessions(project_hash, started_at DESC);
+CREATE INDEX idx_ltm_messages_session_ts
+  ON ltm_messages(session_id, ts);
+CREATE INDEX idx_ltm_tool_calls_session_ts
+  ON ltm_tool_calls(session_id, ts);
+CREATE INDEX idx_ltm_chunks_session_ts
+  ON ltm_chunks(session_id, ts DESC);
+CREATE INDEX idx_ltm_chunks_metadata_gin
+  ON ltm_chunks USING gin (metadata);
+-- pgvector index (HNSW/IVFFlat는 데이터량과 버전에 맞춰 선택)
+```
+
+## 5. 수집(Write Path) 설계
+
+입력 소스:
+
+- 세션 transcript: `ChatRecordingService` 출력 JSON
+- activity log: `session-<id>.jsonl` (debug mode)
+- hook payload: `BeforeTool/AfterTool/SessionEnd` 입력/출력
+
+파이프라인:
+
+1. Parse
+2. PII redaction (정규식 + allowlist)
+3. Normalize (session/message/tool event 스키마화)
+4. Upsert
+5. (옵션) chunking + embedding 생성
+
+장애 대응:
+
+- DB 쓰기 실패 시 `.gemini/tmp/<project_hash>/ltm-spool/*.jsonl`에 적재
+- 백그라운드 재전송 워커가 exponential backoff로 재시도
+
+## 6. 검색(Read Path) 설계
+
+트리거:
+
+- `BeforeAgent`에서 실행 (요청마다 또는 정책 기반 샘플링)
+
+절차:
+
+1. 질의 정규화
+2. metadata pre-filter (project_hash, recent window, tool/domain tag)
+3. hybrid 검색
+
+- keyword (tsvector/BM25 유사)
+- vector (pgvector cosine/L2)
+
+4. 재랭킹 + 중복 제거
+5. 토큰 예산 내 요약
+6. `additionalContext`로 삽입
+
+주입 예시 포맷:
+
+- “Relevant Past Incidents”
+- “Previously Successful Commands”
+- “Known Failure Patterns”
+
+## 7. 보안 및 거버넌스
+
+1. 저장 전 마스킹
+
+- API key, token, password, cookie, authorization header
+
+2. 접근 통제
+
+- DB role 분리: writer / reader / admin
+- 운영자 조회는 read-only role 사용
+
+3. 보존 정책
+
+- raw event: 30~90일
+- summary/chunk: 180~365일
+- 법/정책 요구 시 project별 예외 정책
+
+4. 삭제권 대응
+
+- session_id/project_hash 기준 hard delete + vacuum 운영 절차
+
+## 8. 코드 변경 설계 (정식 통합 기준)
+
+1. 설정
+
+- `packages/cli/src/config/settingsSchema.ts`
+  - `longTermMemory.enabled`
+  - `longTermMemory.provider` (`postgres`)
+  - `longTermMemory.connectionStringEnv`
+  - `longTermMemory.retrieval.topK`
+  - `longTermMemory.retrieval.maxContextTokens`
+  - `longTermMemory.redaction.enabled`
+
+2. 코어 서비스
+
+- 신규:
+  - `packages/core/src/services/historyStore.ts`
+  - `packages/core/src/services/postgresHistoryStore.ts`
+  - `packages/core/src/services/longTermMemoryService.ts`
+- 연동:
+  - `packages/core/src/hooks/hookEventHandler.ts` (Phase A/B 공통 진입점)
+  - `packages/core/src/core/client.ts` (선택: core-native pre-agent retrieval)
+
+3. 문서
+
+- `docs/get-started/configuration.md` 설정 추가
+- `docs/hooks/writing-hooks.md`에 LTM 예시 추가
+
+## 9. 테스트 전략
+
+1. 단위 테스트
+
+- 스키마 매핑, redaction, ranking/scoring, context budget trimming
+
+2. 통합 테스트
+
+- PostgreSQL testcontainer 기반 ingest/retrieve 검증
+- DB down 시 spool fallback 검증
+
+3. 회귀 테스트
+
+- LTM off일 때 기존 동작 불변성 확인
+- 토큰 비용 증가 상한 검증
+
+## 10. 운영 지표
+
+필수 메트릭:
+
+- `ltm_ingest_success_rate`
+- `ltm_ingest_lag_seconds`
+- `ltm_retrieval_latency_ms` (p50/p95/p99)
+- `ltm_context_hit_rate`
+- `ltm_spool_queue_depth`
+
+알람 예시:
+
+- ingest success < 99%
+- retrieval p95 > 500ms (5m 지속)
+- spool depth 급증
+
+## 11. 마이그레이션 계획
+
+1. DDL 적용 + 권한 세팅
+2. 백필 도구로 기존 `chats/*.json` 적재
+3. Hook 기반 read path on
+4. 운영 안정화 후 core-native로 전환
+
+## 12. 오픈 이슈
+
+1. 임베딩 모델 표준(차원, 비용, 지연)
+2. multi-tenant 분리 방식(project_hash vs tenant_id)
+3. 요약 생성 위치(클라이언트/서버/비동기 배치)
+4. compliance에 따른 지역/암호화 키 정책

package/dist/docs/core/long-term-memory-proposal.md

@@ -0,0 +1,112 @@
+# Long-Term Memory (PostgreSQL) Proposal
+
+## 배경
+
+현재 Gemini CLI는 세션 기록을 로컬 파일에 저장합니다.
+
+- 세션 대화: `~/.gemini/tmp/<project_hash>/chats/*.json`
+- 디버그 활동 로그:
+  `~/.gemini/tmp/<project_hash>/logs/session-<session_id>.jsonl` (debug mode)
+- 훅 입력: `transcript_path`가 전달되어 후처리 가능 (`SessionEnd`, `AfterTool`,
+  `BeforeAgent`)
+
+이 구조는 로컬 복구/재개에는 충분하지만, 팀 단위 운영관리(SE) 관점에서는 아래
+요구를 만족하기 어렵습니다.
+
+- 프로젝트/세션/이슈 단위의 통합 검색
+- 장기 이력 기반 의사결정(유사 장애, 이전 조치, 실패 패턴)
+- 감사/거버넌스 및 보존 정책
+
+## 목표
+
+- 작업/도구/결과 로그를 PostgreSQL에 중앙 저장
+- 질의 시 과거 이력을 검색해 현재 작업 컨텍스트로 주입
+- 운영관리 시나리오(장애 대응, 재발 방지, 변경 승인)에서 재사용 가능한 장기
+  메모리 제공
+
+## 비목표
+
+- 기존 `save_memory` 도구 대체
+- 전체 히스토리를 매 턴 모델 컨텍스트에 전부 주입
+- 즉시 완전 자동화(초기 단계는 승인/검토 흐름 유지)
+
+## 제안 아키텍처
+
+### 단계 1 (빠른 적용: Hook 기반)
+
+- `SessionEnd` 훅에서 `transcript_path`를 읽어 PostgreSQL에 upsert
+- `AfterTool` 훅에서 주요 도구 결과를 구조화 저장 (선택)
+- `BeforeAgent` 훅에서 질의와 메타데이터 기반 검색 후 `additionalContext`로 주입
+
+장점:
+
+- 코어 대규모 수정 없이 빠르게 PoC 가능
+- 실패 시 기능 비활성화가 쉬움
+
+한계:
+
+- 훅 스크립트 품질/운영 복잡도에 의존
+- 검색/랭킹/보안 규칙이 분산될 가능성
+
+### 단계 2 (정식 기능: Core 내장)
+
+- `HistoryStore` 인터페이스 + `PostgresHistoryStore` 구현 추가
+- 인제스트/검색/요약을 코어 서비스로 통합
+- 설정(`settings.json`)과 정책(approval/policy/hook) 연동
+
+장점:
+
+- 일관된 실패 처리, 테스트 가능성, 운영 가시성 향상
+- 확장(다른 DB, 하이브리드 검색, 보안정책) 용이
+
+## 추가 구현이 필요한 영역
+
+1. 설정 계층
+
+- `packages/cli/src/config/settingsSchema.ts`: `longTermMemory` 섹션 추가
+  (enabled, provider, dsn/env, retrieval 정책, redaction 옵션)
+- `docs/get-started/configuration.md`: 신규 설정 문서화
+
+2. 저장/조회 인터페이스
+
+- `packages/core/src/services/`:
+  - `historyStore.ts` (interface)
+  - `postgresHistoryStore.ts` (implementation)
+  - `longTermMemoryService.ts` (ingest + retrieve orchestration)
+
+3. 수집 파이프라인
+
+- 소스:
+  - `ChatRecordingService` 세션 JSON
+  - Activity JSONL (옵션)
+  - Hook 이벤트 페이로드
+- 요구사항:
+  - idempotent upsert
+  - 배치/재시도/백오프
+  - 부분 실패 시 로컬 스풀(queue) 저장
+
+4. 검색/주입 경로
+
+- `BeforeAgent` 단계에서 질의 기반 검색
+- top-k 결과를 토큰 예산 내 요약 후 prompt context에 삽입
+- 민감정보 및 prompt-injection 방어 필터 적용
+
+5. 운영 기능
+
+- 백필 스크립트(기존 `chats/*.json` 적재)
+- 보존 정책(TTL), 삭제/익명화, 감사 로그
+- 지표(적재율, 검색적중률, p95 지연, context 기여도)
+
+## 권장 도입 순서
+
+1. Hook 기반 PoC (2~3주)
+2. PostgreSQL 스키마 고정 + 백필 도구
+3. Core 서비스 통합 (read path 먼저)
+4. write path 전환 + 운영 하드닝
+
+## 성공 기준
+
+- 세션 적재 성공률 >= 99.9%
+- 검색 p95 <= 300ms (metadata+vector hybrid 기준)
+- “과거 이력 기반 해결” 비율 증가(운영 KPI)
+- 장애 대응 시 평균 triage 시간 단축