@didim365/agent-cli-core 0.1.1 → 0.1.3

package/dist/docs/configuration.md

@@ -1,108 +0,0 @@
-# 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

@@ -1,105 +0,0 @@
-# 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

@@ -1,254 +0,0 @@
-# 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

@@ -1,112 +0,0 @@
-# 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 시간 단축