xgen-dex-cli 1.2.0

package/docs/PROTOCOL.md

@@ -0,0 +1,187 @@
+# Dex CLI stdio protocol v1
+
+`dex serve --stdio`는 장기 실행 엔진 프로세스를 시작합니다. 전송은 UTF-8 NDJSON이고 각 줄은
+완전한 JSON-RPC 2.0 객체입니다.
+
+## 전송 규칙
+
+- stdin: client request와 notification
+- stdout: server response와 notification
+- stderr: 사람이 읽는 로그와 진단
+- 한 줄에 정확히 하나의 JSON 객체
+- 첫 request는 반드시 `initialize`
+- protocol version은 현재 `1`
+- request ID는 string, number 또는 null
+- 비밀번호를 포함한 request 전체를 로그에 남기지 않음
+
+## 초기화
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"client":{"name":"xgen-vscode","version":"0.1.0"}}}
+```
+
+Response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": 1,
+    "server": { "name": "dex-cli", "version": "0.1.0" },
+    "capabilities": {
+      "profiles": true,
+      "authentication": ["password"],
+      "agents": true,
+      "chatStreaming": true,
+      "chatCancellation": true,
+      "history": true,
+      "localTools": true
+    }
+  }
+}
+```
+
+초기화 전에 다른 method를 부르면 `-32002` 오류가 반환됩니다.
+
+## Methods
+
+### Process
+
+- `initialize({protocolVersion})`
+- `health()`
+- `shutdown()`
+- `exit` notification
+
+### Profiles
+
+- `profile/list()`
+- `profile/set({name, serverUrl})`
+- `profile/use({name})`
+
+### Authentication
+
+- `auth/login({profile?, email, password})`
+- `auth/status({profile?})`
+- `auth/logout({profile?})`
+
+`password`는 stdio frame 안에만 존재하고 저장되지 않습니다. 로그인 결과의 token은 응답에
+포함하지 않고 엔진이 OS keychain에 저장합니다.
+
+### Agents
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "agents/list",
+  "params": {
+    "profile": "corp",
+    "page": 1,
+    "pageSize": 24,
+    "search": "sales",
+    "owner": "personal",
+    "includeHarness": true
+  }
+}
+```
+
+### Local tools
+
+- `localTools/status()`
+- `localTools/list()`
+- `localTools/configure({profile?, enabled?, cwd?, timeoutMs?, allowedRoots?, blockedCommands?, allowDangerous?})`
+- `localTools/run({tool, args})`
+- `localTools/start({profile?, waitMs?})`
+- `localTools/stop()`
+
+Bridge 연결 상태가 바뀌면 다음 notification을 전송합니다.
+
+```json
+{"jsonrpc":"2.0","method":"localTools/status","params":{"running":true,"connected":true,"catalogSynced":true,"advertisedTools":6,"serverTools":6}}
+```
+
+`localTools/configure`의 기본값은 `enabled:false`, `allowDangerous:false`입니다. 활성화된 stdio 엔진은
+`/api/tools/ws/connector-mcp/{userId}`에 인증 WebSocket을 연결하고 `local` 서버의 도구를 광고합니다.
+
+### History
+
+- `history/conversations({profile?})`
+- `history/turns({profile?, workflowId, workflowName?, interactionId})`
+
+### Chat
+
+Start request:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 20,
+  "method": "chat/start",
+  "params": {
+    "profile": "corp",
+    "workflowId": "wf_abc",
+    "workflowName": "Sales Agent",
+    "interactionId": "optional-conversation-id",
+    "input": "hello"
+  }
+}
+```
+
+Start response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 20,
+  "result": {
+    "streamId": "b4df...",
+    "interactionId": "6fb9...",
+    "workflowId": "wf_abc",
+    "workflowName": "Sales Agent"
+  }
+}
+```
+
+Stream notification:
+
+```json
+{"jsonrpc":"2.0","method":"chat/event","params":{"streamId":"b4df...","event":{"kind":"text","content":"안녕"}}}
+```
+
+Terminal notifications:
+
+```json
+{"jsonrpc":"2.0","method":"chat/complete","params":{"streamId":"b4df...","interactionId":"6fb9..."}}
+{"jsonrpc":"2.0","method":"chat/error","params":{"streamId":"b4df...","error":{"code":"network_error","message":"..."}}}
+```
+
+Cancel request:
+
+```json
+{"jsonrpc":"2.0","id":21,"method":"chat/cancel","params":{"streamId":"b4df..."}}
+```
+
+## Errors
+
+표준 JSON-RPC 오류:
+
+- `-32700`: parse error
+- `-32600`: invalid request
+- `-32601`: method not found
+- `-32602`: invalid params
+- `-32002`: initialize required
+- `-32000`: engine error
+
+Engine error의 안정적인 문자열 code는 `error.data.code`에 들어갑니다.
+
+- `auth_required`
+- `auth_invalid`
+- `config_invalid`
+- `credential_store_unavailable`
+- `network_error`
+- `not_found`
+- `protocol_mismatch`
+- `usage_error`

package/docs/TUI.md

@@ -0,0 +1,46 @@
+# Dex terminal UI
+
+## 실행 조건
+
+`dex`와 `dex ui`는 stdin/stdout이 모두 TTY이고 `TERM`이 `dumb`가 아니며 CI가 아닐 때 TUI를
+실행합니다. pipe, redirect, JSON 출력, `serve --stdio`는 기존 headless 경로를 사용합니다.
+
+## 첫 실행
+
+1. XGEN Gateway URL 입력
+2. `default` profile 생성
+3. 이메일과 비밀번호 로그인
+4. Agent 목록 로드
+5. 대시보드 진입
+
+비밀번호는 login 호출 직전에 컴포넌트 state에서 지우며 token은 기존과 동일하게 OS
+keychain에만 저장합니다.
+
+## 대시보드
+
+- 넓은 터미널: Agent 목록과 채팅을 좌우로 표시
+- 좁은 터미널: `Tab`으로 Agent 목록과 채팅 화면 전환
+- SSE `text` 이벤트는 현재 Assistant 메시지에 누적
+- tool 이벤트는 실행 중/완료/실패 상태로 갱신
+- node/status 이벤트는 채팅 하단 상태 줄에 표시
+- `Esc`는 현재 `AbortController`를 취소
+- 같은 interaction ID를 재사용해 대화를 이어감
+- 로컬 도구가 활성화되어 있으면 첫 채팅 전에 도구 bridge와 카탈로그를 연결
+
+## 명령 팔레트
+
+`Ctrl+K`:
+
+- 새 대화
+- 대화 기록
+- profile 전환
+- 로그아웃
+- 종료
+
+## 터미널 안전성
+
+- TUI 진입점은 dynamic import chunk로 분리
+- 일반 CLI와 stdio RPC는 Ink를 로드하지 않음
+- stdout protocol에 TUI 로그를 기록하지 않음
+- Ctrl+C/Ctrl+Q/오류/unmount 시 cursor와 raw mode 복원
+- `NO_COLOR` 환경은 Ink의 색상 비활성화 동작을 따름

package/docs/VSCODE.md

@@ -0,0 +1,41 @@
+# VS Code extension architecture
+
+`vscode-extension/`은 `dex-cli`를 로컬 엔진으로 사용하는 얇은 VS Code 클라이언트입니다.
+
+```text
+       VS Code Webview View
+              │
+              │ typed commands and state
+              ▼
+      Extension Host controller
+              │
+              │ JSON-RPC 2.0 over UTF-8 NDJSON
+              ▼
+        dex serve --stdio
+              │
+              ▼
+       DexEngine / OS keychain / XGEN
+```
+
+## 경계
+
+- 확장은 XGEN HTTP/SSE endpoint를 직접 호출하지 않습니다.
+- protocol version은 CLI와 동일한 `1`로 고정합니다.
+- stdout은 protocol frame 전용이고 stderr는 `XGEN Dex` Output Channel로 전달합니다.
+- profile, credential, 로컬 도구 설정의 실제 저장과 실행은 CLI가 소유합니다.
+- 채팅 stream은 확장이 생성한 `streamId`로 notification을 라우팅합니다.
+
+## UI
+
+- `xgenDex.chat`: Agent 선택, 스트리밍 채팅, 계정·회사/환경·로컬 도구 설정을 전환하는 단일 Webview View
+- Status Bar: 현재 사용자, 로그인 필요, 오프라인, CLI 오류 상태
+- Command Palette: profile, auth, history, engine lifecycle 명령
+
+Webview는 서버 문자열을 `innerHTML`로 넣지 않고 `textContent`만 사용합니다. 입력창은 브라우저의
+composition event와 `KeyboardEvent.isComposing`을 확인해 한글 조합 완료 Enter를 메시지 전송으로
+오인하지 않습니다.
+
+설정 화면의 로컬 도구 카드는 `localTools/status`, `localTools/configure`, `localTools/start` RPC만
+사용합니다. 활성화, 작업 폴더, 허용 경로, 차단 명령, 실행 제한 시간을 저장할 수 있고
+`localTools/status` notification으로 브리지 연결 상태를 갱신합니다. 위험 명령 허용을 처음 켤 때는
+VS Code의 modal 확인을 한 번 더 요구합니다.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "xgen-dex-cli",
+  "version": "1.2.0",
+  "description": "XGEN Dex CLI — 터미널에서 XGEN 에이전트와 대화하고, 이 컴퓨터의 셸·파일·MCP 를 에이전트에게 빌려 줍니다.",
+  "type": "module",
+  "bin": {
+    "dex": "dist/cli.js",
+    "xgen-dex": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx --test test/args.test.ts test/config.test.ts test/engine.test.ts test/mode.test.ts test/rpc.test.ts test/tui-state.test.ts test/tui.test.tsx",
+    "verify": "npm run check && npm test && npm run build && node dist/cli.js --version",
+    "vscode:install": "npm --prefix vscode-extension install",
+    "vscode:verify": "npm --prefix vscode-extension run verify",
+    "verify:all": "npm run verify && npm run vscode:verify"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ink": "^6.8.0",
+    "keytar": "^7.9.0",
+    "react": "^19.2.0",
+    "string-width": "^8.2.2",
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.25.0",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/PlateerLab/xgen-dex-core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PlateerLab/xgen-dex-core.git",
+    "directory": "apps/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/PlateerLab/xgen-dex-core/issues"
+  },
+  "keywords": [
+    "xgen",
+    "dex",
+    "agent",
+    "llm",
+    "cli",
+    "tui",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}