# ConnectAI — Project Architecture Context

<!-- ASTRA:AUTO-START -->

## Snapshot
- **Workspace**: `connectai` `v2.2.193` _(absolute path varies by environment; resolved from the active VS Code workspace)_
- **Description**: The personal intelligence layer for Antigravity and VS Code. A private cognitive partner for deep project context, memory, and proactive strategic decision-making.
- **Stack**: TypeScript, Node.js, VS Code Extension, LM Studio SDK, Test runner
- **Stats**: 416 source files, ~70,115 lines across 5 top-level modules.

## Last Refresh
- **Time**: 2026-05-29T06:58:50.818Z
- **Files newly analysed**: 3
- **Files reused from cache**: 413

## Directory Map
```mermaid
mindmap
  root((connectai))
    src/
      features/
      sidebar/
      lib/
      agent/
      retrieval/
      core/
    media/
    tests/
      helpers/
      integration/
      mocks/
    core_py/
    docs/
      records/
      docs/
      Meeting/
```

## Module Dependencies
> Arrows: which top-level module imports from which.
```mermaid
flowchart LR
    src["src/<br/>262 files"]
    media["media/<br/>6 files"]
    tests["tests/<br/>37 files"]
    core_py["core_py/<br/>6 files"]
    docs["docs/<br/>105 files"]
    tests --> src
```

## Entry Points
> Files to read first when learning the codebase.
- `src/extension.ts`
- `media/sidebar.html` — Astra
- `package.json` — npm package manifest

## Hub Files
> Imported by many other files — touching these has wide blast radius.
- `src/utils.ts` — referenced by **87** files
- `src/agent.ts` — referenced by **34** files
- `src/config.ts` — referenced by **33** files
- `src/core/services.ts` — referenced by **15** files
- `src/features/company/index.ts` — referenced by **14** files · Public API for 1인 기업 모드. Consumers (sidebarProvider, chatHandlers, command handlers) import from this barrel so internal layout can move around without touching every call site.
- `src/features/company/types.ts` — referenced by **14** files · Type definitions for the 1인 기업 (One-Person Company) mode. The mode turns the user into a virtual CEO that dispatches work to a roster of specialist agents. Each turn produces a session directory conta
- `src/sidebarProvider.ts` — referenced by **11** files
- `src/lib/contextManager.ts` — referenced by **10** files · Context Manager (컨텍스트 한계 관리) "context length = 132k" 는 "답변을 132k 토큰까지 생성해도 된다" 가 아닙니다. 시스템 프롬프트 + 대화 기록 + 입력 문서 + 생성될 답변 + 여유분 ≤ context length 이 모듈은 요청을 보내기 전에 입력 토큰을 추정하고, - 동적으로 출력 상한(maxTokens)을 계

## Modules

### `src/` — 262 files, ~52,385 lines

**Sub-directories**
- `src/features/` (92) — Astra Office — public API. 다음 세션에서 추가될 OfficeSnapshot presenter / schema 도 같은 entry 로 노출 예정. 현재 노출: full webview panel H
- `src/sidebar/` (35) — Brain profile lifecycle 의 pure helpers — sidebarProvider 의 add/edit/delete 흐름에서 modal UI 와 config 쓰기를 제외한 데이터 변환 만 격리. 현
- `src/lib/` (28) — Astra Mode Architecture Context Builder. 의도: 사용자가 Astra 자체의 mode 디자인 (Guard vs Multi-Agent 가 별도 모드여야 하는지) 을 묻는 메타 질문에 답할
- `src/agent/` (26) — Post-hoc Self-Check — 답변 완료 후 LLM 한 번 호출로 3가지 평가. 사용자 제안: "[Self-Check] 단계 — 이 답변이 사용자 질문에 직접 답하는가 / 규칙 준수 / 논리 모순 없는가".
- `src/retrieval/` (16) — Actionability Scoring — 검색 결과를 "현재 작업 상태" 신호로 재가중. 기존 TF-IDF (단어 매칭) + recency (시간) 만으로는 "지금 이 사용자가 하고 있는 작업과 직접 연결 된 문서
- `src/core/` (15) — Astra Path Resolver (경로 해결기) Astra의 모든 데이터 파일(.astra 디렉토리)의 경로를 중앙에서 관리합니다. 확장 프로그램의 설치 경로(extensionUri) 기반으로 .astra 디렉토
- `src/memory/` (9) — Distillation Loop — stale Episodic Memory → Long-Term "episode-digest" 승급. 배경: Episodic Memory 가 무한히 누적되면 검색 노이즈. 30일+ 지
- `src/extension/` (8) — 8 files (.ts)
- `src/docs/` (6) — Bug: Edited agent.ts Edited agent.ts Edited agent.ts Edited agent.ts Edited agent.ts ...
- `src/integrations/` (6) — Per-chat conversation history for the Telegram bot. Why this exists: the previous bot was stateless — every inbound mess
- `src/lmstudio/` (4) — 4 files (.ts)
- `src/skills/` (4) — 4 files (.ts)

**Key files**
- `src/utils.ts` (471 lines)
- `src/config.ts` (550 lines)
- `src/agent.ts` (1568 lines)
- `src/features/company/types.ts` (446 lines) — Type definitions for the 1인 기업 (One-Person Company) mode. The mode turns the user into a virtual CEO that dispatches work to a roster of specialist agents. Each turn produces a session directory conta
- `src/core/services.ts` (176 lines)
- `src/sidebarProvider.ts` (3186 lines)
- `src/lib/contextManager.ts` (278 lines) — Context Manager (컨텍스트 한계 관리) "context length = 132k" 는 "답변을 132k 토큰까지 생성해도 된다" 가 아닙니다. 시스템 프롬프트 + 대화 기록 + 입력 문서 + 생성될 답변 + 여유분 ≤ context length 이 모듈은 요청을 보내기 전에 입력 토큰을 추정하고, - 동적으로 출력 상한(maxTokens)을 계
- `src/features/company/companyConfig.ts` (896 lines) — State + config plumbing for 1인 기업 모드. Two surfaces: - CompanyState (runtime data: enabled flag, company name, which agents are active, per-agent model overrides). Persisted in VS Code's globalState so
- `src/integrations/telegram/telegramClient.ts` (154 lines)
- `src/lib/paths.ts` (151 lines)
- `src/agent/actions/types.ts` (41 lines)
- `src/skills/agentKnowledgeMap.ts` (374 lines)
- `src/retrieval/types.ts` (66 lines) — Retrieval Types (검색 결과 통합 타입) 모든 검색 소스(Brain, Memory, Project, Episode)의 결과를 통합 인터페이스로 정의합니다.
- `src/memory/types.ts` (151 lines) — Memory Type Definitions (메모리 타입 정의) Astra의 5-Layer Cognitive Memory System의 모든 타입을 정의합니다. ① Short-Term ② Long-Term ③ Project ④ Procedural ⑤ Episodic
- `src/retrieval/scoring.ts` (541 lines) — Scoring Engine — TF-IDF + Bilingual Tokenizer 단순 includes() 키워드 매칭을 넘어서, TF-IDF 가중치 기반의 문서 스코어링을 제공합니다. 한국어/영어 양국어 토크나이저를 포함합니다.
- `src/features/stocks/types.ts` (53 lines) — Stocks 모듈 공유 타입. investresults/targetstocks.json 스키마를 그대로 받아서, ConnectAI 의 <workspace>/.astra/stocks.json 으로 옮긴 뒤 같은 필드명을 유지. 한글 필드명은 사용자의 도메인 데이터라 변경하지 않는다 — 마이그레이션 충돌 회피 + 사용자가 직접 JSON 편집할 때 frictio
- `src/lib/contextBuilders/promptDetection.ts` (85 lines) — 사용자 prompt 의 의도 분류 류 detection helpers. 모두 stateless 정규식 매칭. 옛 코드는 agent.ts 의 private 메서드로 박혀 있었는데, system prompt 빌더 (buildJarvisProjectBriefContext 등) 가 이걸 의존하면서 god-file 안에서 서로 얽힘. 헬퍼만 먼저 떼면 의존 그래프가
- `src/retrieval/lessonHelpers.ts` (325 lines) — Lesson / Experience Memory — pure helpers (no vscode dependency) "Lesson" = a markdown file in the active brain that captures a past mistake/risk and how to avoid repeating it. Identified by a lessons
- `src/security.ts` (159 lines)
- `src/features/secondBrainTrace.ts` (792 lines)
- `src/features/providers/types.ts` (63 lines) — Cloud LLM provider routing — model id prefix → provider id 매핑. Prefix 규칙: openrouter:anthropic/claude-3.5-sonnet → { provider: 'openrouter', model: 'anthropic/claude-3.5-sonnet' } anthropic:claude-3-5
- `src/integrations/telegram/telegramBot.ts` (270 lines)
- `src/lib/contextBuilders/localProjectIntent.ts` (233 lines)
- `src/lib/engine.ts` (1114 lines)
- `src/lmstudio/streamer.ts` (252 lines)

### `media/` — 6 files, ~7,671 lines

**Key files**
- `media/sidebar.css` (2114 lines) — Stylesheet
- `media/sidebar.js` (3933 lines)
- `media/sidebar.html` (539 lines) — Astra
- `media/settings-panel.html` (406 lines) — Astra Settings
- `media/settings-panel.css` (210 lines) — Stylesheet
- `media/settings-panel.js` (469 lines)

### `tests/` — 37 files, ~5,875 lines
*Depends on*: `src/`

**Sub-directories**
- `tests/helpers/` (1) — MockLLMClient — IAIService 의 Mock 구현체. 의도: 회사 모드 dispatcher / ChunkedWriter / ceoPlanner 등 LLM 을 호출하는 코드 경로를 CI 환경에서도 테스
- `tests/integration/` (1) — MockLLMClient 자체의 sanity test. 이게 통과하면 dispatcher / ceoPlanner / ChunkedWriter 등 IAIService 를 받는 코드가 실제 LLM 없이 단위 / inte
- `tests/mocks/` (1) — 1 files (.js)

**Key files**
- `tests/helpers/mockLLMClient.ts` (112 lines) — MockLLMClient — IAIService 의 Mock 구현체. 의도: 회사 모드 dispatcher / ChunkedWriter / ceoPlanner 등 LLM 을 호출하는 코드 경로를 CI 환경에서도 테스트 가능하게. 실제 Ollama / LM Studio 없이도 응답을 미리 정의하거나 동적으로 생성 가능. 사용 예: const ai = new 
- `tests/agentEngine.test.ts` (413 lines) — AgentEngine Tests — Chunked Writer Architecture 예전 buildup(planner → researcher → reflector → writer → synthesizer)을 단일 ChunkedWriter 의 outline → section[N] → polish 로 교체한 뒤의 회귀 테스트. 다루는 범위: 1. ErrorC
- `tests/lmStudioLifecycle.test.ts` (326 lines) — Unit tests for ModelLifecycleManager. Strategy: inject mock ILMStudioClient and a simple in-memory IActivityTracker. No real LM Studio or SDK is touched — the manager file does not import the SDK dire
- `tests/localPathPreflight.test.ts` (520 lines)
- `tests/telegramBot.test.ts` (363 lines) — Unit tests for TelegramBot + truncateForTelegram. Strategy: - TelegramBot is driven by an injected ITelegramClient stub. We script getUpdates to return queued batches and assert that: - the offset cur
- `tests/lmStudioStreamer.test.ts` (222 lines) — Unit tests for LMStudioStreamer. Strategy: inject a fake ILMStudioClient that returns a fake model handle whose respond() yields a controllable async iterable. No real SDK or WebSocket touched.
- `tests/secondBrainTrace.test.ts` (407 lines)
- `tests/approvalQueue.test.ts` (164 lines) — Unit tests for ApprovalQueue. Strategy: drive enqueue → approve / reject / clear / pre-empt directly, confirm the onChange event fires at the right moments and callbacks fire exactly once.
- `tests/projectScaffolder.test.ts` (135 lines) — Unit tests for FileSystemProjectScaffolder. Drives against a real temp directory so end-to-end file IO + path-traversal defenses are exercised.
- `tests/resilience_stress.test.ts` (197 lines) — Resilience & Boundary Stress Test Suite (v2.77.3) 이 테스트는 ConnectAI 엔진이 극한의 환경(인증 실패, 네트워크 차단, 타임아웃 등)에서 얼마나 안정적으로 복구되고, 신뢰성 지표(Resilience Metrics)를 정확히 기록하는지 검증합니다.
- `tests/skillInjectionService.test.ts` (172 lines) — Unit tests for FileSystemSkillInjectionService. Strategy: drive the service against a real temp directory so path-traversal defenses and writeFileSync paths are exercised end-to-end. The service accep
- `tests/dataProcessor.test.ts` (87 lines) — / <reference types="jest" />
- `tests/findBrainFilesCache.test.ts` (80 lines) — Unit tests for findBrainFiles TTL cache.
- `tests/integration/mockLLMClient.test.ts` (86 lines) — MockLLMClient 자체의 sanity test. 이게 통과하면 dispatcher / ceoPlanner / ChunkedWriter 등 IAIService 를 받는 코드가 실제 LLM 없이 단위 / integration 테스트 가능. 향후 dispatcher 의 multi-stage flow 같은 큰 integration 테스트는 이 mock 을 
- `tests/officeSchema.test.ts` (241 lines)
- `tests/paths.test.ts` (84 lines) — Unit tests for the centralized path resolver.
- `tests/systemSpecs.test.ts` (90 lines) — Unit tests for SystemSpecs + HeuristicModelMemoryEstimator. Strategy: - HeuristicModelMemoryEstimator is pure — directly drive it with model ids. - NodeSystemSpecsProvider depends on os. so we test: a
- `tests/transaction.test.ts` (68 lines) — / <reference types="jest" />
- `tests/vulnerability.test.ts` (60 lines) — / <reference types="jest" />
- `tests/brainIndex.test.ts` (107 lines)
- `tests/calendarApi.test.ts` (131 lines)
- `tests/contextManager.test.ts` (149 lines)
- `tests/icsParser.test.ts` (134 lines)
- `tests/lessonHelpers.test.ts` (191 lines)
- `tests/projectChronicle.test.ts` (199 lines)

### `core_py/` — 6 files, ~409 lines

**Key files**
- `core_py/events.py` (64 lines)
- `core_py/inference.py` (91 lines)
- `core_py/loader.py` (61 lines)
- `core_py/monitoring.py` (56 lines)
- `core_py/optimizer.py` (55 lines)
- `core_py/queue_worker.py` (82 lines)

### `docs/` — 105 files, ~3,775 lines

**Sub-directories**
- `docs/records/` (92) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 프로젝트 코드 리뷰 해줄 수 있어? 개선할 부분이 있는지, 그러고...
- `docs/docs/` (5) — Bug: Viewed integrationretrieval.test.ts:1-59 integrationretrieval.test.ts를 통해 ...
- `docs/Meeting/` (0)

**Key files**
- `docs/TELEGRAM_REMOTE_EXECUTION_PLAN.md` (452 lines) — Telegram Remote Execution 기획서
- `docs/AgentEngine_Architecture.md` (314 lines) — AgentEngine Architecture Document
- `docs/records/ConnectAI/timeline.md` (227 lines) — Project Timeline
- `docs/ASTRA_OFFICE_REFACTOR.md` (198 lines) — Astra Office Refactor — Design Doc
- `docs/EXPERIENCE_MEMORY_PLAN.md` (122 lines) — Experience Memory (Mistake / Lesson Loop) — Implementation Plan
- `docs/records/ConnectAI/development/2026-05-02_connectai_project_knowledge_overview.md` (121 lines) — Astra Project Knowledge Overview
- `docs/records/ConnectAI/development/2026-05-03_connectai_project_knowledge_overview.md` (121 lines) — Astra Project Knowledge Overview
- `docs/Advanced_Features_Implementation_Guide.md` (40 lines) — Advanced Features Implementation Guide
- `docs/docs/records/docs/bugs/BUG-0001-viewed-integration-retrieval-test-ts-1-59-integration-retrie.md` (16 lines) — Bug: Viewed integrationretrieval.test.ts:1-59 integrationretrieval.test.ts를 통해 ...
- `docs/docs/records/docs/chronicle.config.json` (11 lines) — JSON configuration
- `docs/docs/records/docs/project-profile.md` (31 lines) — Project Profile
- `docs/docs/records/docs/README.md` (18 lines) — docs Chronicle Records
- `docs/docs/records/docs/timeline.md` (7 lines) — Project Timeline
- `docs/PROJECT_CHRONICLE_GUARD_ROADMAP.md` (43 lines) — Project Chronicle Guard: Search Engine Roadmap
- `docs/records/ConnectAI/bugs/BUG-0001-volumes-data-project-antigravity-connectai-프로젝트-코드-리뷰-해줄-수-있.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 프로젝트 코드 리뷰 해줄 수 있어? 개선할 부분이 있는지, 그러고...
- `docs/records/ConnectAI/bugs/BUG-0002-지금-내가-분석-요청하고-너가-답을-줄때-아래-템플릿에-맞춰-답을-써주고-있는데-개선-포인트가-있는지-확인해.md` (16 lines) — Bug: 지금 내가 분석 요청하고 너가 답을 줄때 아래 템플릿에 맞춰 답을 써주고 있는데, 개선 포인트가 있는지 확인해줘. ## 내가 보는 위험 가장 큰...
- `docs/records/ConnectAI/bugs/BUG-0003-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0004-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0005-다시한번-답줘-volumes-data-project-antigravity-connectai-내-질문에-대한-.md` (16 lines) — Bug: 다시한번 답줘. /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는...
- `docs/records/ConnectAI/bugs/BUG-0006-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0007-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0008-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0009-문제점을-읽고-어떻게-개선하는게-최선인지-분석해주면-좋겠어-알겠습니다-지금부터-connectai-프로젝트-에.md` (16 lines) — Bug: 문제점을 읽고 어떻게 개선하는게 최선인지 분석해주면 좋겠어. 알겠습니다. 지금부터 ConnectAI 프로젝트에만 완전히 집중하겠습니다. ...
- `docs/records/ConnectAI/bugs/BUG-0010-문제점을-읽고-어떻게-개선하는게-최선인지-분석해주면-좋겠어-알겠습니다-지금부터-connectai-프로젝트-에.md` (16 lines) — Bug: 문제점을 읽고 어떻게 개선하는게 최선인지 분석해주면 좋겠어. 알겠습니다. 지금부터 ConnectAI 프로젝트에만 완전히 집중하겠습니다. ...
- `docs/records/ConnectAI/bugs/BUG-0011-문제점을-읽고-어떻게-개선하는게-최선인지-분석해주면-좋겠어-알겠습니다-지금부터-connectai-프로젝트-에.md` (16 lines) — Bug: 문제점을 읽고 어떻게 개선하는게 최선인지 분석해주면 좋겠어. 알겠습니다. 지금부터 ConnectAI 프로젝트에만 완전히 집중하겠습니다. ...

## VS Code Extension Surface
- **Extension ID**: `g1nation.astra`
- **Activation events**: `onStartupFinished`
- **Commands** (29):
  - `g1nation.newChat` — Astra: New Chat
  - `g1nation.exportChat` — Astra: Export Chat as Markdown
  - `g1nation.explainSelection` — Astra: Explain Selected Code
  - `g1nation.focusChat` — Astra: Focus Chat Input
  - `g1nation.showBrainNetwork` — Astra: Show Brain Topology
  - `g1nation.approval.focus` — Astra: Focus Approval Panel
  - `g1nation.scaffoldProject` — Astra: Scaffold New Project
  - `g1nation.telegram.setBotToken` — Astra: Set Telegram Bot Token
  - `g1nation.telegram.clearBotToken` — Astra: Clear Telegram Bot Token
  - `g1nation.telegram.testConnection` — Astra: Test Telegram Connection
  - `g1nation.settings.focus` — Astra: Open Settings Panel
  - `g1nation.skills.editKnowledgeMap` — Astra: Edit Agent ↔ Knowledge Map
  - `g1nation.openChat` — Astra: Open Chat (Editor Column)
  - `g1nation.setupDatacollect` — Astra: Setup Datacollect Dependencies (yt-dlp, youtube-transcript-api)
  - `g1nation.lesson.create` — Astra: New Lesson (Experience Memory)
  - `g1nation.lesson.fromConversation` — Astra: New Lesson from Current Conversation
  - `g1nation.lesson.manage` — Astra: Browse / Manage Lessons
  - `g1nation.architecture.refresh` — Astra: Refresh Project Architecture Context
  - `g1nation.architecture.detach` — Astra: Detach Project Architecture Context
  - `g1nation.architecture.attach` — Astra: Attach Project Architecture Context
  - `g1nation.architecture.open` — Astra: Open Project Architecture Doc
  - `g1nation.company.toggle` — Astra: Toggle 1인 기업 Mode
  - `g1nation.company.manage` — Astra: Manage 1인 기업 Agents
  - `g1nation.company.openSessions` — Astra: Open 1인 기업 Sessions Folder
  - `g1nation.company.pixelOffice.open` — Astra: Open Pixel Office (Full Screen)
  - `g1nation.calendar.connect` — Astra: Google Calendar (iCal) 연결 📅
  - `g1nation.calendar.refresh` — Astra: Google Calendar 새로고침 📅
  - `g1nation.calendar.connectOAuth` — Astra: Google Calendar OAuth 연결 (쓰기) 🔐
  - `g1nation.devilAgent.toggle` — Astra: Toggle Devil Agent 🎭
- **Configuration** (121 settings):
  - `g1nation.multiAgentEnabled` *(boolean)* _(default: `false`)_ — Enable Multi-Agent Workflow (Planner -> Researcher -> Writer) for complex tasks.
  - `g1nation.datacollectBridgeUrl` *(string)* _(default: `"http://127.0.0.1:3002"`)_ — Wiki/Datacollect MCP Bridge URL. /research, /benchmark, /youtube chat slash commands route here. The Bridge must be running (`npm run bridge` in the Datacollect project).
  - `g1nation.datacollectSavePath` *(string)* _(default: `""`)_
  - `g1nation.datacollectCrawlDepth` *(number)* _(default: `1`)_
  - `g1nation.datacollectMaxPages` *(number)* _(default: `8`)_
  - `g1nation.datacollectSynthesisTemperature` *(number)* _(default: `0.1`)_
  - `g1nation.chatTemperature` *(number)* _(default: `0.3`)_
  - `g1nation.meetUsesTasks` *(boolean)* _(default: `true`)_
  - `g1nation.meetUsesCalendar` *(boolean)* _(default: `false`)_
  - `g1nation.teamVoiceGuide` *(string)* _(default: `""`)_
  - `g1nation.memoryEnabled` *(boolean)* _(default: `true`)_ — Enable layered memory injection before each model response.
  - `g1nation.memoryShortTermMessages` *(number)* _(default: `8`)_ — Number of recent conversation messages included as short-term memory.
  - `g1nation.memoryMediumTermSessions` *(number)* _(default: `5`)_ — Number of recent saved chat sessions included as medium-term memory.
  - `g1nation.memoryLongTermFiles` *(number)* _(default: `6`)_ — Number of relevant Second Brain markdown files included as long-term memory.
  - `g1nation.ollamaUrl` *(string)* _(default: `"http://127.0.0.1:11434"`)_ — Base URL for Ollama or LM Studio. Default: http://127.0.0.1:11434
  - `g1nation.defaultModel` *(string)* _(default: `"gemma4:e2b"`)_ — Default model name to use for chat requests.
  - `g1nation.requestTimeout` *(number)* _(default: `300`)_ — Request timeout in seconds. Default: 300
  - `g1nation.contextLength` *(number)* _(default: `32768`)_ — Model context window in tokens (prompt + generation combined). Set this to the value your loaded model is actually running with in LM Studio / Ollama. Astra budgets prompt and output against this so i
  - `g1nation.maxOutputTokens` *(number)* _(default: `4096`)_ — Upper bound on tokens generated per response. The effective limit is reduced automatically when the prompt is large so input + output stays within g1nation.contextLength. Default: 4096
  - `g1nation.contextSafetyMargin` *(number)* _(default: `2048`)_ — Tokens kept free as a safety buffer for token-count estimation error. Default: 2048
  - `g1nation.contextOverflowPolicy` *(string)* _(default: `"stopAtLimit"`)_ — Fallback behavior (LM Studio) if the prompt still exceeds the context window after Astra's own budgeting. 'stopAtLimit' fails clearly so you notice; 'truncateMiddle'/'rollingWindow' drop content silen
  - `g1nation.autoCompactHistory` *(boolean)* _(default: `true`)_ — Automatically drop the oldest conversation messages from the request when the prompt would exceed the context budget (the on-screen chat history is unaffected). Default: true
  - `g1nation.smallModelContextCap` *(number)* _(default: `0`)_ — Optional safety knob, OFF by default (0). Some very small models (≤3B) emit an empty/EOS response when given a prompt near their context window even though it nominally fits. If you observe that with 
  - `g1nation.autoContinueOnOutputLimit` *(boolean)* _(default: `true`)_ — When a reply is cut off because it hit the output-token limit, Astra continues it internally (compressed request — original question + the answer so far, not the whole context again) and shows one mer
  - `g1nation.maxAutoContinuations` *(number)* _(default: `4`)_ — Maximum number of automatic continuation rounds per reply (prevents runaway loops). Raise it (e.g. 5–6) for long-form answers on slow local models; set 0 to disable auto-continuation. Default: 4
  - `g1nation.finalOnlyRetryOnThoughtLeak` *(boolean)* _(default: `true`)_ — If the model emits only hidden reasoning (<think>, <|channel|>thought, "Thinking Process:" …) and no user-visible answer, Astra silently re-asks it for the final answer only. Hidden reasoning is never
  - `g1nation.lmStudio.idleTimeoutMs` *(number)* _(default: `300000`)_ — Auto-eject the loaded LM Studio model after this many milliseconds of inactivity. Set to 0 to disable. Default: 300000 (5 minutes).
  - `g1nation.lmStudio.autoLoadOnSelect` *(boolean)* _(default: `true`)_ — Automatically load LM Studio models into memory when selected from the Astra sidebar.
  - `g1nation.lmStudio.sampling.topP` *(number)* _(default: `0.9`)_ — Nucleus sampling cutoff. Small / quantized models often spew wrong-neighbour tokens (한글 깨짐: 붕괴→붕점) when the tail is wide. Lower (0.8–0.9) tightens; 1.0 disables. Applied to both SDK and REST paths.
  - `g1nation.lmStudio.sampling.topK` *(number)* _(default: `20`)_ — Top-K sampling cutoff. 0 disables. Default 20 — tighter for small models, raise to 40–80 for large models that already sample well.
  - `g1nation.lmStudio.sampling.minP` *(number)* _(default: `0.05`)_ — Min-P floor — discards tokens with probability below this fraction of the top token. Good defence against rare-token glitches. 0 disables.
  - `g1nation.lmStudio.sampling.repeatPenalty` *(number)* _(default: `1.1`)_ — Repeat / frequency penalty to curb stutter (것입니다서입니다…). 1.0 disables. Values 1.05–1.2 are typical.
  - `g1nation.lmStudio.statsInBudget` *(boolean)* _(default: `true`)_ — Show token/s and time-to-first-token from LM Studio prediction stats in the context-budget badge after each turn (SDK path only).
  - `g1nation.lmStudio.draftModel` *(string)* _(default: `""`)_ — [Speculative decoding] LM Studio model key of a small draft model (e.g. 'gemma-2b-it') used to accelerate the main model. Empty disables. 1.5–3x throughput on large models. The draft must be downloade
  - `g1nation.lmStudio.load.flashAttention` *(boolean)* _(default: `true`)_ — [Load option] Enable Flash Attention when loading models. Faster generation + lower memory on compatible hardware, especially helpful for long contexts. Default: true.
  - `g1nation.lmStudio.load.gpuOffloadRatio` *(string)* _(default: `"max"`)_ — [Load option] How much of the model to offload to GPU. 'max' = all (default), 'off' = CPU only, or a number 0–1 (e.g. '0.5' = half). Numeric strings are parsed.
  - `g1nation.lmStudio.load.offloadKVCacheToGpu` *(boolean)* _(default: `true`)_ — [Load option] Keep KV cache on GPU memory. Faster but requires VRAM headroom. Default: true.
  - `g1nation.lmStudio.load.keepModelInMemory` *(boolean)* _(default: `true`)_ — [Load option] Prevent the model from being swapped out of system memory. Improves interactive responsiveness; raises RAM use. Default: true.
  - `g1nation.lmStudio.load.useFp16ForKVCache` *(boolean)* _(default: `false`)_ — [Load option] Store KV cache in FP16 (halves cache memory). Tiny quality impact for most models — try if you run out of VRAM at long contexts. Default: false.
  - `g1nation.lmStudio.load.evalBatchSize` *(number)* _(default: `0`)_ — [Load option] Token batch size during evaluation. 0 = engine default. Higher (512–1024) improves prefill speed on GPU at the cost of memory.
  - `g1nation.localBrainPath` *(string)* _(default: `""`)_ — Folder path for your local Second Brain knowledge base. Leave empty to use the default folder.
  - `g1nation.brainProfiles` *(array)* _(default: `[]`)_ — Multiple brain profiles. Each item supports id, name, localBrainPath, secondBrainRepo, and description.
  - `g1nation.activeBrainId` *(string)* _(default: `""`)_ — Active brain profile id used for the current chat context.
  - `g1nation.secondBrainRepo` *(string)* _(default: `""`)_ — Optional GitHub repository URL used for Second Brain sync.
  - `g1nation.autoPushBrain` *(boolean)* _(default: `false`)_ — Automatically commit and push Second Brain changes after updates.
  - `g1nation.maxContextSize` *(number)* _(default: `32000`)_ — Maximum character count for active file context. Default: 32000
  - `g1nation.maxAutoSteps` *(number)* _(default: `50`)_ — Maximum autonomous steps the agent can take per request. Default: 50
  - `g1nation.dryRun` *(boolean)* _(default: `false`)_ — If enabled, the agent will ask for approval before committing any file changes.
  - `g1nation.telegram.enabled` *(boolean)* _(default: `false`)_ — Enable the Telegram bot integration. When on, Astra polls a bot you configure and replies to incoming messages. Off by default — Astra remains 100% local until you opt in.
  - `g1nation.telegram.allowedChatIds` *(array)* _(default: `[]`)_ — Optional allowlist of Telegram chat IDs that may message the bot. When empty, every chat that messages the bot is accepted (use with caution).
  - `g1nation.telegram.defaultAgent` *(string)* _(default: `""`)_ — Agent name (matches an entry in the Agent ↔ Knowledge map) used to scope Second Brain retrieval for Telegram replies. Empty falls back to the map's defaultAgent, then to whole-brain search.
  - `g1nation.telegram.agentByChatId` *(object)* _(default: `{}`)_ — Per-chat override of the Telegram agent. Keys are stringified chat IDs, values are agent names from the knowledge map. Overrides telegram.defaultAgent for the listed chats.
  - `g1nation.telegram.contextChunks` *(number)* _(default: `6`)_ — How many Second Brain excerpts to inject into Telegram replies. Set 0 to disable RAG (plain prompt only).
  - `g1nation.skillKnowledgeMapPath` *(string)* _(default: `""`)_ — Absolute path to the agent ↔ knowledge mapping JSON. When empty, defaults to '<workspace>/.astra/agent-knowledge-map.json'.
  - `g1nation.skillKnowledgeMap` *(object)* _(default: `{}`)_ — Inline fallback for the agent ↔ knowledge mapping. Used only when the JSON file is missing. Shape: { defaultAgent?, agents: [{ name, knowledgeFolders, model?, description? }] }. Folder paths can be ab
  - `g1nation.agentSkillsPath` *(string)* _(default: `""`)_ — Absolute path to the agent skills folder (`.agent/skills/*.md`). When empty, defaults to '<workspace>/.agent/skills'. Use this on Windows or when your skills live outside the workspace.
  - `g1nation.embeddingModel` *(string)* _(default: `""`)_ — Embedding model registered in LM Studio / Ollama (e.g. 'text-embedding-bge-small-en-v1.5', 'nomic-embed-text', 'multilingual-e5-small'). When empty, Astra uses TF-IDF only. When set, the brain is embe
  - `g1nation.embeddingBlendAlpha` *(number)* _(default: `0.5`)_ — Hybrid score blend: 0 = pure TF-IDF (sparse / keyword), 1 = pure embedding cosine (dense / semantic), 0.5 = balanced. Only used when g1nation.embeddingModel is set. Default 0.5.
  - `g1nation.conflictHighlightingEnabled` *(boolean)* _(default: `true`)_ — Conflict Surface — 검색된 출처에서 충돌/논란 신호 감지 시 [CONFLICT WARNINGS] 블록을 시스템 프롬프트에 주입. LLM 이 상충되는 관점을 명시하고 사용자 판단에 위임하도록. 기본 켜짐.
  - `g1nation.conflictSeverityThreshold` *(string)* _(default: `"medium"`)_ — Conflict 자기-신호 surface 시 최소 severity 임계. low=가장 민감(노이즈 가능), medium=균형(기본), high=강한 충돌만.
  - _…and 61 more_

## Dependencies
- **Runtime** (2): `@lmstudio/sdk`, `pdf-parse`
- **Dev** (8): `@types/jest`, `@types/node`, `@types/vscode`, `@vercel/ncc`, `esbuild`, `jest`, `ts-jest`, `typescript`

## README Excerpt
> Pulled from the project root README — first ~2 KB.

# Astra (by g1nation)

Astra는 **Antigravity 및 VS Code** 환경에서 작동하는 대표님 전용 **지능형 운영 레이어(Personal Intelligence Layer)**입니다. 단순한 명령 수행을 넘어, 프로젝트의 맥락과 대표님의 의사결정 패턴을 학습하여 최적의 전략적 조언을 제공하는 독립적인 인지 파트너입니다.

## 🌌 Antigravity & VS Code Unified Assistant

Astra는 범용 AI와 달리 특정 플랫폼에 종속되지 않으며, Antigravity 워크스페이스의 깊은 맥락과 VS Code의 강력한 개발 도구를 하나로 연결합니다. 

### 1. 전용 지능형 판단 체계 (Personal Cognition Layer)
v4.0 운영 정책이 코어에 이식되어 데이터의 신뢰도를 대표님의 기준에 맞춰 스스로 평가합니다. 상충되는 정보 발견 시 즉각적인 **[CONFLICT WARNING]**을 통해 객관적인 판단 근거를 제시합니다.

### 2. 고밀도 전략 지식망 (Strategic Knowledge Hub)
대표님의 Second Brain과 Antigravity 내의 모든 지식을 온톨로지 기반으로 구조화합니다. 비즈니스 전략, 기술 아키텍처, 리스크 관리가 하나로 통합된 지식 그래프를 통해 추론의 깊이를 보장합니다.

### 3. 선제적 파트너십 (Proactive Partnership)
작업이 완료된 후, 대표님이 다음에 내려야 할 **전략적 의사결정 포크(Decision Forks)**를 선제적으로 제안합니다. 사용자의 명령을 기다리지 않고, 프로젝트의 흐름을 먼저 읽고 길을 제시합니다.

## 🛠️ 주요 기능 및 권한

Astra는 대표님의 명시적인 승인 하에 로컬 시스템의 강력한 제어 권한을 행사하여 생산성을 극대화합니다.

| 작업 범주 | 설명 |
| :--- | :--- |
| **플랫폼 최적화** | Antigravity 워크스페이스와 VS Code 사이의 유기적인 맥락 전환 및 동기화를 지원합니다. |
| **자율 워크플로우** | 다중 에이전트 협업을 통해 복잡한 비즈니스 요구사항을 즉시 실행 가능한 단계별 계획으로 분해합니다. |
| **지식 자산화** | 흩어진 정보들을 P-Reinforce v3.0 표준에 맞게 위키화하여 영구적인 지식 자산으로 전환합니다. |
| **보안 및 프라이버시** | 100% 로컬 환경에서 작동하여 대표님의 소중한 데이터가 외부로 유출되지 않음을 보장합니다. |

## 🚀 설치 및 시작하기

### 패키지 설치
1. **g1nation**에서 배포된 최신 **v2.65.0** VSIX 파일을 확보합니다.
2. VS Code 명령 팔레트(`Cmd+Shift+P`)에서 **Extensions: Install from VSIX**를 선택하여 설치합니다.
3. Antigravity 환경과 연동하여 나만의 지능형 레이어를 활성화합니다.

---
**Designed for High-Performance Decision Making.**
Copyright (C) **g1nation**. All rights reserved.

_Last auto-scan: 2026-05-29T06:58:50.818Z · signature `e7ea4eff`_
<!-- ASTRA:AUTO-END -->

## Purpose

Astra (g1nation) — **로컬 LLM 기반의 개인 지능형 운영 레이어**. VS Code 확장으로 LM Studio / Ollama 와 채팅하면서 *프로젝트 컨텍스트 / 메모리 / 작업 자동화* 를 단일 UI 에서 처리. 100% 로컬 (cloud LLM 은 opt-in 라우팅).

### Top-level 동작 흐름

```
User ↘                                              ↗ webview (chat UI)
       sidebar.html / sidebar.js  ←——  chatHandlers
                        │                    │
                        │                    ├─ slash router (/research /youtube /stocks 등)
                        │                    │
                        ↓                    ↓
              SidebarChatProvider ──→  AgentExecutor (agent.ts, 1,529 lines)
                                              │
                       ┌──────────────────────┴──────────────────────┐
                       ↓                      ↓                      ↓
              handlePrompt phases      executeActions (8 그룹)   LLM I/O (agent/llm)
              (agent/handlePrompt)     (agent/actions)            createStreamingRequest
                                                                  streamChatOnce
                                                                  callNonStreaming
                       │
                       ↓
              [PRIOR TURN CONCLUSION]   ← 대화 연속성 anchor
              + Mode Bridge + Context Blocks + System Prompt + Budget
```

### 핵심 디자인 패턴

**1. God-file 분해 (R50–R59, 2026-05).** `agent.ts` 2731→1529 lines, `extension.ts` 1145→349 lines. 25개 신규 모듈 (`src/agent/**`, `src/extension/**`). 패턴:
- *Pure free functions + deps object* — `this.X` 의존성을 callback dep 으로 명시 (e.g. `callNonStreaming(deps, params)`)
- *Thin wrappers on the class* — AgentExecutor 의 메서드는 deps 묶어서 free function 으로 위임. 외부 caller signature 보존.
- Action handlers (15+ tags) 는 `HandlerContext` 공유 ctx 객체로 통일 — 8개 그룹 (file/run/list/brain/calendar/sheets/tasks).
- handlePrompt 1,100줄 → 7 phase 모듈 (buildTurnContextBlocks / buildModeBridgeContext / build{Agent,Astra}ModeSystemPrompt / computeBudgetedRequest / processFinalAnswer / applyAutoContinuation).

**2. 대화 연속성 (v2.2.150~157).** 작은 로컬 모델 (gemma 4B 등) 이 follow-up 정정/보강 turn 에 echo/parrot 하는 문제 해결:
- `[PRIOR TURN CONCLUSION]` block — 직전 assistant 답변의 첫 문장을 system prompt 에 anchor
- `[CONVERSATION CONTINUITY & REVISION]` rule — echo 금지, 최소 3-5 문장 구조 강제
- *Thin follow-up classifier* (`isThinFollowUp`) — 짧은 follow-up turn 에서 Guard 의 4-section boilerplate (`## 요청 요약` 등) suppress
- *Slash 결과 chatHistory mirror* — slash 명령 결과를 webview *와 함께* agent.chatHistory 에 push (capture wrapper). 다음 turn LLM 이 직전 명령 출력 인식. `getHistory()` 가 filtered copy 반환하는 silent bug fix 포함.

**3. Slash 명령 시스템.** `src/features/datacollect/slashRouter.ts` 의 registry. 등록된 명령: `/research /benchmark /youtube /blog /wikify /meet /stocks`. webview 의 `/` 자동완성 dropdown 으로 노출. 각 명령은 `(arg, view, context) => Promise<boolean>` 시그니처 통일.

**4. Stocks feature (v2.2.152~158).** 새 도메인 — 한국 주식 모니터링/발굴:
- `.astra/stocks.json` 저장소 (workspace root)
- Yahoo Finance 현재가 갱신, `g1nation.stocks.spreadsheetId` 로 Google Sheets 동기화 (calendar OAuth scope 재사용)
- KST 09:00 / 15:00 watcher 자동 트리거 → Telegram 보고서
- **8 키워드 자동 필터** (ROE/성장성/유동성/수익성/영업효율/기술력/안정성/PBR) — `llmJudge.ts` 와 `stockDiscovery.ts` 가 동일 임계값 공유
- `/stocks discover` — Naver 비공식 JSON API (`m.stock.naver.com/api/...`) 로 시가총액 페이지 + 펀더멘털 (ROE/영업이익률/유보율) 크롤 후 8 키워드 필터 → 통과한 종목 → LLM Top 5 매력도 분석 → Telegram 자동 발송
- `/stocks judge <symbol>` — LLM 으로 4-criteria 필터 자동 판정 + JSON 업데이트

**5. 5-Layer Cognitive Memory.** `src/memory/`:
- Short-Term (대화 단기) / Long-Term (Second Brain) / Project (프로젝트 기록) / Procedural (스킬) / Episodic (세션 요약)
- TF-IDF + 한/영 이중 토크나이저 (`src/retrieval/scoring.ts`)
- 옵션: embedding hybrid (`g1nation.embeddingModel` 설정 시 dense+sparse blend)
- Knowledge Mix policy — Second Brain 의존도 (0-100) 사용자 조절 가능

**6. 1인 기업 모드 (Company Mode).** `src/features/company/`:
- 가상 회사 — 사용자 = CEO, 에이전트 = 직원. 명령 분류기 → dispatcher → 직군별 specialist → CEO 검수 → 산출물
- 각 turn 은 session directory 에 `_brief.md / _report.md / 에이전트별 산출물` 영구 기록
- LLM 호출 인터페이스: `IAIService.chat({system, user})` (mock 가능 → `tests/helpers/mockLLMClient.ts`)

**7. Context budget (`src/lib/contextManager.ts`).** 매 turn 마다 system + history + input 의 토큰 예산 계산, output 상한 동적 조절. `smallModelContextCap` 옵션으로 ≤3B 모델의 EOS-first 환각 회피.

**8. Cloud LLM routing (`src/features/providers/`).** `openrouter:` / `anthropic:` / `gemini:` prefix 가 model id 에 있으면 자동 cloud SDK 라우팅. SSE 응답은 OpenAI 호환 형식으로 normalize → 로컬 path 와 동일 consumer.

### 진입 파일 (학습 순서)

1. **`src/extension.ts`** — activation, 모든 wiring (사이드바 / approval / telegram / stocks watcher / slash router)
2. **`src/sidebarProvider.ts`** — webview lifecycle, message dispatch (chatHandlers / settings)
3. **`src/agent.ts`** — AgentExecutor (thin wrappers + chatHistory 상태)
4. **`src/agent/handlePrompt/`** — 한 turn 의 7-phase pipeline
5. **`src/features/stocks/`** — 최근 새 도메인 사례 (slash + watcher + LLM + Telegram 통합)

### 활성 작업 (2026-05)

- *완료*: god-file 분해 R50–R59, Stocks feature 전체 파이프라인, 대화 연속성 fix
- *진행 가능 (paused)*: `/stocks discover` 의 시가총액 범위 자동 유도 (사용자 드롭 요청)
- *남은 큰 영역*: `slashRouter.ts` (1,127 lines), `dispatcher.ts` (1,364 lines), `sidebarProvider.ts` (3,194 lines) — 별도 god-file 분해 대상이나 ROI 검토 필요