# Telegram Remote Execution 기획서

## 1. 목적

현재 Astra의 Telegram 연동은 사용자의 메시지를 받아 Second Brain RAG 컨텍스트를 붙이고 AI 답변을 Telegram으로 돌려주는 "원격 질의응답" 기능이다. 사용자가 원하는 다음 단계는 Telegram에서 지시한 업무를 실제 로컬 컴퓨터의 VS Code 워크스페이스에서 진행하게 만드는 것이다.

이 기능의 목표는 Telegram을 안전한 원격 작업 지시 채널로 확장하는 것이다. 단, 보안상 Telegram 메시지가 곧바로 임의의 파일 변경이나 터미널 명령으로 이어지면 안 된다. 기본 정책은 "읽기 작업은 제한적으로 자동 실행, 쓰기/삭제/명령 실행은 승인 기반"으로 한다.

## 2. 현재 구조 요약

- `src/extension.ts`
  - Telegram bot을 생성하고 `handle(text, chatId)`에서 메시지를 처리한다.
  - 현재는 `AIService.chat()`만 호출한다.
  - `AgentExecutor.handlePrompt()`나 `executeActions()` 경로를 사용하지 않는다.

- `src/integrations/telegram/telegramBot.ts`
  - Telegram long polling, allowlist, enrollment, send retry를 담당한다.
  - handler가 반환한 문자열을 Telegram으로 보낸다.

- `src/agent.ts`
  - 사이드바 채팅 요청을 처리한다.
  - AI 응답 안의 action tag를 파싱해 파일 생성/수정/삭제, 파일 읽기, 명령 실행, URL 읽기 등을 수행한다.
  - `dryRun`이 켜진 경우 `TransactionManager`와 `ApprovalQueue`를 통해 승인/롤백 흐름을 제공한다.

- `src/features/approval/approvalQueue.ts`
  - 현재 승인 대기 작업을 0..1개 관리한다.
  - approve/reject callback을 실행한다.

## 3. 핵심 제품 방향

Telegram 원격 실행은 기존 사이드바 Agent 실행 기능을 그대로 노출하는 것이 아니라 별도 게이트웨이를 둔다.

추천 명칭:

- `TelegramTaskGateway`
- 위치: `src/integrations/telegram/telegramTaskGateway.ts`

역할:

- Telegram 메시지를 "단순 답변"과 "로컬 작업 지시"로 분류한다.
- 로컬 작업 지시일 경우 작업 계획을 생성한다.
- 위험도를 평가한다.
- 읽기 전용 작업은 바로 실행할 수 있다.
- 파일 변경, 삭제, 터미널 명령은 승인 토큰을 발급하고 대기시킨다.
- 승인 후에만 실제 로컬 작업을 실행한다.

## 4. 사용자 경험

### 4.1 기본 명령

Telegram에서 다음 명령을 지원한다.

- `/ask 질문`
  - 현재처럼 Second Brain 기반 답변만 생성한다.

- `/task 업무지시`
  - 로컬 워크스페이스에서 수행할 작업으로 해석한다.
  - 예: `/task README를 읽고 설치 가이드가 부족한 부분을 보완해줘`

- `/status`
  - 현재 실행 중이거나 승인 대기 중인 작업 상태를 보여준다.

- `/approve 작업ID`
  - 승인 대기 중인 작업을 실행한다.

- `/reject 작업ID`
  - 승인 대기 중인 작업을 폐기한다.

- `/cancel`
  - 현재 실행 중인 Telegram-origin 작업을 중단한다.

### 4.2 예시 흐름

사용자:

```text
/task package.json이랑 README 보고 설치 방법 문서 보완해줘
```

Astra:

```text
작업 계획을 만들었습니다.

작업 ID: tg-20260512-184233
위험도: 파일 수정 필요

예상 작업:
1. package.json 읽기
2. README.md 읽기
3. README.md의 설치 섹션 수정

변경 대상:
- README.md

실행하려면:
/approve tg-20260512-184233

취소하려면:
/reject tg-20260512-184233
```

사용자:

```text
/approve tg-20260512-184233
```

Astra:

```text
승인되었습니다. 작업을 실행합니다.
```

완료 후:

```text
작업 완료.

변경 파일:
- README.md

요약:
- npm install 단계 추가
- VSIX 설치 방법 보완
- LM Studio/Ollama 설정 안내 추가
```

## 5. 보안 정책

### 5.1 Telegram allowlist 필수

원격 실행 기능은 `g1nation.telegram.allowedChatIds`가 비어 있으면 비활성화한다.

이유:

- 현재 설정은 allowedChatIds가 비어 있으면 모든 chat을 허용한다.
- 질의응답에는 괜찮을 수 있지만 원격 실행에는 위험하다.

정책:

- `/task`, `/approve`, `/reject`, `/cancel`, `/status`는 allowlist 등록 chat에서만 동작한다.
- allowlist가 비어 있으면 다음 메시지를 반환한다.

```text
원격 작업 기능은 허용된 Telegram chat에서만 사용할 수 있습니다.
Settings에서 내 채널 자동 등록을 먼저 완료해주세요.
```

### 5.2 작업 위험도

작업을 4단계로 분류한다.

- `read_only`
  - 파일 목록 조회, 파일 읽기, Second Brain 검색, 코드 분석.
  - 자동 실행 가능.

- `file_write`
  - 파일 생성/수정.
  - 승인 필요.

- `destructive`
  - 파일 삭제, 대량 변경, git clean/reset, dependency reinstall.
  - 명시적 승인 필요. 기본적으로 2단계 확인을 권장한다.

- `command`
  - 터미널 명령 실행.
  - 승인 필요.
  - `sanitizeCommand()` 통과 필요.
  - 장기적으로 allowlist 기반 command policy가 필요하다.

### 5.3 경로 제한

- 모든 파일 작업은 기존 `validatePath(workspaceRoot, targetPath)`를 통과해야 한다.
- 워크스페이스 밖 파일은 기본 차단한다.
- Second Brain 경로는 읽기/쓰기 정책을 별도로 둔다.

### 5.4 기본값

새 설정을 추가한다.

```json
{
  "g1nation.telegram.remoteExecutionEnabled": false,
  "g1nation.telegram.remoteReadOnlyAutoRun": true,
  "g1nation.telegram.remoteRequireApproval": true,
  "g1nation.telegram.remoteAllowCommands": false,
  "g1nation.telegram.remoteMaxTaskSteps": 8
}
```

권장 기본값:

- remoteExecutionEnabled: false
- remoteReadOnlyAutoRun: true
- remoteRequireApproval: true
- remoteAllowCommands: false
- remoteMaxTaskSteps: 8

## 6. 목표 아키텍처

```text
TelegramBot
  -> TelegramTaskGateway.handle(text, chatId)
      -> command parser
      -> permission check
      -> task planner
      -> risk classifier
      -> approval store
      -> TelegramTaskExecutor
          -> AgentExecutor or shared ActionExecutor
          -> TransactionManager
          -> ApprovalQueue
      -> Telegram reply
```

## 7. 구현 전략

### Phase 1: 명령 라우팅과 승인 대기

목표:

- `/ask`, `/task`, `/status`, `/approve`, `/reject` 명령을 Telegram에서 인식한다.
- 실제 파일 변경은 아직 하지 않아도 된다.
- `/task`는 작업 계획과 승인 요청 메시지를 반환한다.

작업:

- `telegramTaskGateway.ts` 추가
- `TelegramCommand` 타입 정의
- `PendingTelegramTask` 타입 정의
- in-memory pending task store 추가
- extension.ts의 Telegram handler에서 gateway 호출

성공 기준:

- `/ask`는 기존 답변 경로 유지
- `/task`는 작업 ID와 계획을 반환
- `/status`는 pending task를 보여줌
- `/approve`와 `/reject`는 pending task 상태를 변경

### Phase 2: 읽기 전용 작업 실행

목표:

- Telegram에서 요청한 코드 분석, 파일 읽기, 파일 목록 조회를 자동으로 수행한다.

작업:

- `TelegramReadOnlyTool` 추가
- 허용 action:
  - list files
  - read file
  - search text
  - Second Brain retrieval
- 결과를 요약해 Telegram으로 반환

성공 기준:

- `/task src 구조 분석해줘`가 실제 파일 목록과 주요 파일 내용을 읽고 답변한다.
- 워크스페이스 밖 경로 요청은 차단된다.

### Phase 3: 파일 변경 작업 승인 실행

목표:

- 파일 생성/수정 요청을 Telegram에서 승인 후 실행한다.

권장 구현:

- `AgentExecutor.executeActions()`는 현재 private이므로 바로 재사용하기 어렵다.
- 장기적으로는 action 실행부를 `src/core/actionExecutor.ts`로 추출한다.
- 단기 MVP는 `AgentExecutor.handlePrompt()`를 Telegram origin으로 호출하는 방식도 가능하다.

추천 구조:

```text
ActionExecutor
  - parseActionTags(aiMessage)
  - previewActions(actions)
  - execute(actions, options)
  - rollback(transactionId)
```

성공 기준:

- `/task docs에 사용법 문서 만들어줘`
- Astra가 계획과 변경 예정 파일을 보여줌
- `/approve id` 후 파일 생성
- `/reject id` 후 아무 변경 없음

### Phase 4: 명령 실행 지원

목표:

- 제한된 터미널 명령을 승인 후 실행한다.

정책:

- 기본 비활성화.
- `remoteAllowCommands`가 true일 때만 동작.
- `sanitizeCommand()` 통과 필요.
- command allowlist를 설정으로 관리하는 것을 권장한다.

추가 설정:

```json
{
  "g1nation.telegram.remoteCommandAllowlist": [
    "npm test",
    "npm run test",
    "npm run compile",
    "git status",
    "git diff"
  ]
}
```

성공 기준:

- `/task 테스트 실행해줘`는 승인 요청을 만든다.
- `/approve id` 후 허용된 명령만 실행한다.
- 차단된 명령은 실행하지 않고 이유를 반환한다.

## 8. AI 프롬프트 정책

Telegram task planner용 system prompt를 별도로 둔다.

```text
You are Astra Telegram Task Planner.
Your job is to convert a Telegram message into a safe local workspace task plan.

Rules:
- Never execute actions directly.
- Produce a concise task plan.
- Classify risk as read_only, file_write, destructive, or command.
- List expected files or directories when possible.
- If the request is ambiguous, ask one short clarifying question.
- If the user requests computer-wide access outside the workspace, refuse and explain the workspace boundary.
- Prefer read-only inspection before proposing writes.

Output JSON only:
{
  "intent": "ask" | "task" | "approve" | "reject" | "status" | "cancel",
  "risk": "read_only" | "file_write" | "destructive" | "command",
  "summary": "...",
  "steps": ["..."],
  "targets": ["..."],
  "requiresApproval": true,
  "clarifyingQuestion": ""
}
```

## 9. 데이터 모델

```ts
export type TelegramTaskRisk = 'read_only' | 'file_write' | 'destructive' | 'command';
export type TelegramTaskStatus = 'planned' | 'pending_approval' | 'running' | 'completed' | 'rejected' | 'failed' | 'cancelled';

export interface PendingTelegramTask {
  id: string;
  chatId: number;
  createdAt: number;
  status: TelegramTaskStatus;
  risk: TelegramTaskRisk;
  originalText: string;
  summary: string;
  steps: string[];
  targets: string[];
  requiresApproval: boolean;
  approvalToken?: string;
}
```

## 10. Telegram 응답 포맷

Telegram은 길이 제한이 있으므로 짧고 명령 중심으로 응답한다.

승인 대기:

```text
작업 대기 중

ID: tg-xxxx
위험도: file_write
대상: README.md

실행: /approve tg-xxxx
취소: /reject tg-xxxx
```

완료:

```text
작업 완료

변경:
- README.md

요약:
- 설치 섹션 보완
- 로컬 모델 설정 설명 추가
```

차단:

```text
차단됨

이 작업은 워크스페이스 밖 파일에 접근하려고 합니다.
Telegram 원격 실행은 현재 열린 VS Code 워크스페이스 내부에서만 허용됩니다.
```

## 11. 테스트 계획

단위 테스트:

- command parser
- allowlist 필수 정책
- risk classifier
- pending task store
- approve/reject 상태 전환
- workspace 밖 path 차단
- command allowlist 차단

통합 테스트:

- `/ask` 기존 응답 유지
- `/task` 계획 생성
- `/task` read_only 자동 실행
- `/task` file_write 승인 대기
- `/approve` 후 실행
- `/reject` 후 실행 안 됨
- allowedChatIds 비어 있을 때 원격 실행 차단

회귀 테스트:

- 기존 Telegram RAG 답변이 깨지지 않아야 한다.
- Telegram token 저장/삭제/연결 테스트가 기존처럼 동작해야 한다.
- 사이드바 Approval Panel과 충돌하지 않아야 한다.

## 12. 최종 권장 MVP

가장 안전하고 빠른 MVP 범위:

1. `/ask`, `/task`, `/status`, `/approve`, `/reject` 명령 추가
2. allowlist가 비어 있으면 `/task` 차단
3. read-only 작업만 자동 실행
4. file write와 command는 승인 대기까지만 구현
5. action 실행부는 다음 단계에서 `ActionExecutor`로 추출

이 MVP만으로도 사용자는 Telegram에서 "프로젝트 분석해줘", "이 파일 읽고 요약해줘", "어떤 파일을 고쳐야 하는지 계획 세워줘"를 원격으로 시킬 수 있다. 이후 승인 실행까지 붙이면 Telegram이 완전한 원격 작업 지시 인터페이스가 된다.