tabby-agentdeck 0.3.0 → 1.0.0

package/dist/config.d.ts

@@ -17,11 +17,89 @@ export declare const LAYOUT_DEFAULTS: {
     sidebarWidth: number;
     /** 상/하 도킹일 때의 사이드바 높이 (px). 경계선 드래그로 바뀐다 */
     sidebarHeight: number;
+    /**
+     * 미리보기 패널이 붙는 방향 — 'right' | 'left'.
+     * 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥), 패널이 터미널 쪽(안)에 앉는다.
+     */
+    viewerDock: string;
+    /** 미리보기 패널 폭 (px). 경계선 드래그로 바뀐다 */
+    viewerWidth: number;
 };
 /** @hidden */
 export declare class AgentDeckConfigProvider extends ConfigProvider {
     defaults: {
         agentDeck: {
+            /**
+             * 결과물 미리보기 패널(viewPanel.ts)이 지금 열려 있나.
+             *
+             * 사이드바 `▤` 버튼이나 `agentdeck-view` 핫키로 토글하면 이 값이 바뀌고,
+             * 다음 기동 때 그대로 복원한다 — 문서를 띄워 놓고 쓰는 사람에게는 그게 기본 화면이다.
+             */
+            viewerOpen: boolean;
+            /**
+             * 화면에 찍힌 파일 경로를 주워 최근 목록에 쌓는다.
+             *
+             * 에이전트를 가리지 않는 유일한 경로다 — Claude Code 처럼 훅이 있는 CLI 만 되는 게
+             * 아니라 Codex·Gemini 도 만진 파일을 화면에 찍기 때문이다(viewer.ts 주석).
+             * 비용은 탭당 400ms 마다 정규식 한 번이고, 끄면 수동으로 열 때만 쓰게 된다.
+             */
+            viewerScrape: boolean;
+            /**
+             * 에이전트가 만진 파일을 **패널에 미리 얹어 둔다** (닫혀 있어도).
+             *
+             * 기본 켬. 패널이 닫혀 있는 동안에도 최근 목록과 "다음에 열면 보여줄 파일" 을
+             * 계속 갈아 두므로, 작업이 한창일 때 `▤` 를 누르면 **그때까지 만진 파일들이
+             * 칩으로 쌓여 있고 본문은 가장 최근 파일**이다 (`변경` 모드였으면 그 자리에서
+             * diff 를 다시 읽는다). 끄면 아무것도 자동으로 하지 않는다 — 경로 수집만 남고
+             * 무엇을 볼지는 사람이 칩·`＋`·드롭으로 고른다.
+             *
+             * 이 값이 `false` 면 `viewerAutoOpen` 은 의미가 없다 (읽어두지 않으니 열 것도 없다).
+             */
+            viewerPreload: boolean;
+            /**
+             * 새 파일을 주우면 **닫힌 패널을 스스로 연다.**
+             *
+             * **기본 끔** (2026-09-10 유저 결정). 여닫기는 사람 몫이라는 뜻이다 — 작업 중에
+             * 패널이 저절로 열리면 터미널이 좁아지고 읽던 화면이 밀린다. 대신 위 `viewerPreload`
+             * 가 내용을 계속 채워 두므로, 열고 싶을 때 열면 이미 최신이다.
+             * 켜면 결과물이 나오는 순간 패널이 열리면서 그 파일을 띄운다.
+             */
+            viewerAutoOpen: boolean;
+            /**
+             * @deprecated 0.18.0 부터 `viewerPreload` + `viewerAutoOpen` 두 토글로 갈랐다.
+             *
+             * 목록(`open`/`show`/`manual`) 하나로는 "읽어두기" 와 "자동으로 열기" 가 한 축에
+             * 얹혀 있어서, 사람이 고를 때 두 결정을 한꺼번에 해야 했다. 남겨 두는 이유는
+             * 이미 값을 적어 둔 설정 파일 때문이고, 기동 때 한 번 두 토글로 옮긴 뒤 비운다
+             * (`migrateFollow`, deck.service 의 `migrateFollowConfig`).
+             */
+            viewerFollowMode: "" | "open" | "show" | "manual";
+            /**
+             * @deprecated 0.17.0 부터 `viewerFollowMode` 로, 0.18.0 부터 위 두 토글로 옮겼다.
+             *
+             * boolean 하나가 "자동으로 열기" 와 "새 파일로 바꾸기" 를 같이 쥐고 있어서,
+             * **"패널은 내가 열고 닫되 열어 둔 동안에는 따라와라"** 를 표현할 수 없었다.
+             * 마이그레이션이 `false` 를 읽고 나면 기본값(`true`)으로 되돌려 다시 읽지 않는다.
+             */
+            viewerFollow: boolean;
+            /**
+             * 패널 **밖**(터미널 위)에 파일을 끌어다 놓았을 때 무엇을 할지.
+             *
+             * 순정 Tabby 는 그 경로를 터미널에 붙여넣는다(그래서 `cat <경로>` 가 쉽다). 그 동작은
+             * 그대로 두고, **미리보기로 열지를 물어본다** — 자동으로 화면을 바꾸면 붙여넣기만
+             * 원했던 사람의 화면을 빼앗는다 (2026-09-09 유저: "한번 물어보긴 해야 할 듯").
+             *
+             *  - `ask`    : 확인 배너를 띄워 `패널에 띄우기` / `경로 붙여넣기` 를 고르게 한다 (기본)
+             *  - `always` : 묻지 않고 패널에 띄운다
+             *  - `paste`  : 묻지 않고 경로만 터미널에 붙여넣는다
+             *  - `never`  : 우리가 개입하지 않는다 — 순정 Tabby 동작 그대로
+             *
+             * 배너의 `다시 묻지 않기` 를 체크하고 버튼을 누르면 그 선택이 `always`/`paste` 로
+             * 저장된다. 되돌리려면 설정 창에서 `물어본다` 로 바꾼다.
+             */
+            viewerDropOpen: "ask" | "always" | "paste" | "never";
+            /** 최근 목록(패널 위쪽 칩)에 남겨 두는 파일 수 */
+            viewerRecentMax: number;
             /**
              * 훅이 상태를 밀어 넣는 TCP 채널의 포트 (127.0.0.1 전용).
              *
@@ -62,12 +140,135 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
             autoDetect: boolean;
             /** 사이드바에 경과 시간 표시 */
             showElapsed: boolean;
+            /**
+             * 세션이 지금 돌리고 있는 **백그라운드 서브에이전트 개수**를 줄에 보인다
+             * (`❖ 3`, 툴팁에 무엇을 시켜 놨는지 + 가장 오래된 것의 경과 시간).
+             *
+             * 기본으로 켠다 — 얻는 것이 "저 탭이 사람 없이도 일이 도는 중인지" 이고 그것을 볼
+             * 다른 수단이 없다(훅은 세션 **하나**의 상태만 알려 준다, `subagents.ts` 주석).
+             * 0 개면 아무것도 그리지 않으므로(deck.service `renderTab`) 서브에이전트를 안 쓰는
+             * 사람의 화면은 0.12.0 까지와 똑같다 — 켜 둬서 잃는 것이 없다.
+             *
+             * 비용은 세션당 **2초에 `stat` 한 번**이고, 파일이 자란 만큼만 비동기로 읽는다
+             * (실측 대화기록 13MB — 동기로 읽으면 UI 가 멈춘다).
+             * 끄면 읽기도 표시도 멈춘다: 끈 기능이 대화기록 파일을 계속 여는 일은 없다
+             * (`notify.service` `scanSubagents`).
+             */
+            subagentCount: boolean;
             /**
              * 사이드바 탭을 상태 우선순위(waiting → error → running → done → idle)로 정렬한다.
              * 같은 상태끼리는 탭 순서를 지킨다. 기본은 끔 — 순정 탭바와 같은 탭 순서로 보인다.
              * 헤더의 상태별 집계는 이 값과 무관하게 항상 보인다.
              */
             sortByStatus: boolean;
+            /**
+             * 사이드바 헤더 아래에 **세션 검색 줄**을 둔다 (제목 · 작업이름 · 작업 폴더로 좁히기,
+             * 헤더의 상태 칩을 눌러 그 상태만 보기).
+             *
+             * 기본으로 켠다 — 탭이 몇 개뿐일 때도 잃는 것은 26px 한 줄이고, 탭이 많아지는 순간
+             * 목록을 눈으로 훑는 비용이 그보다 훨씬 크다. 세로가 짧은 상/하 도킹에서 그 한 줄이
+             * 아까운 사람만 끄면 된다.
+             *
+             * **여기 저장하는 것은 기능 on/off 뿐이다.** 검색어와 상태 필터는 설정에 남기지 않는다
+             * (deck.service `searchQuery` 주석) — 다음 기동에 필터가 살아 있으면 목록이 좁혀진
+             * 채로 떠서 "탭이 사라졌다" 로 읽힌다. 그 오해는 이 기능이 주는 이득보다 비싸고,
+             * 되살릴 값어치도 없다(검색은 "지금 이것을 찾는다" 는 한순간의 행위다).
+             * 이 값을 끄면 걸려 있던 필터도 같이 지운다 — 감춰진 필터가 남는 것이 가장 위험하다.
+             */
+            searchBox: boolean;
+            /**
+             * 사이드바를 **키보드로** 다룬다 — 핫키(`agentdeck-focus-list`, 기본 `Ctrl-Shift-L`)로
+             * 목록에 들어가 ↑↓ 로 훑고, Enter 로 그 탭으로 전환, Esc 로 터미널에 돌아온다.
+             * 검색창에서 ↓ 를 누르면 결과 목록으로 내려가고, 첫 줄에서 ↑ 면 검색창으로 돌아온다.
+             * 그룹 헤더도 지나가며 Enter 로 접었다 펼 수 있다.
+             *
+             * **이동만으로는 탭이 바뀌지 않는다** (포커스 ≠ 선택). 여섯 개쯤 띄워 두고 훑을 때
+             * 줄마다 활성 탭이 바뀌면 터미널 화면이 계속 튀어 훑기 자체가 불가능하다
+             * (`deck.service.ts` `navFocus` 주석).
+             *
+             * 기본으로 켠다 — **포커스가 사이드바에 없는 동안은 키를 한 개도 가로채지 않는다.**
+             * 리스너가 document 가 아니라 목록 엘리먼트(`.ad-list`)에 걸려 있어서, 핫키를 누르거나
+             * 검색창에 들어가지 않으면 이벤트가 아예 오지 않는다(`wireListKeys` 주석).
+             * 끄면 핫키·검색창 ↓ 가 모두 no-op 이 되고 링도 그리지 않는다.
+             */
+            keyboardNav: boolean;
+            /**
+             * 목록 끝에서 ↑↓ 를 한 번 더 누르면 반대쪽 끝으로 감싼다.
+             *
+             * 기본은 끔 — 감싸면 "맨 아래에 왔다" 는 신호가 사라지고, 목록이 한 번에 위로 튀어
+             * 화면이 다시 그려진 것처럼 보인다. 끝에서 끝으로 갈 일은 Home/End 가 받는다.
+             *
+             * 켜도 **맨 위의 ↑ 는 검색창으로 나간다**(검색 줄이 보일 때). 그 경계를 감싸기에
+             * 내주면 목록에서 검색창으로 돌아갈 키가 없어진다 — 검색↔목록 왕복이 이 기능의
+             * 요구사항이라 감싸기보다 앞에 둔다 (`deck.service.ts` `moveNav`).
+             */
+            keyboardNavWrap: boolean;
+            /**
+             * `Ctrl+W` 로 지금 탭을 닫는다 (터미널에서 누르면 활성 탭, 목록이 키보드를 갖고
+             * 있으면 포커스 줄의 탭 — `nav.ts` `pickCloseTarget`).
+             *
+             * **`keyboardNav` 에 매달아 둔다** — 키보드로 목록을 훑다가 버릴 탭을 만나는 것이
+             * 이 키의 쓰임새이고, 키보드 조작을 끈 사람에게 터미널 키를 빼앗을 이유가 없다.
+             * 그래서 `keyboardNav` 가 꺼져 있으면 이 값이 `true` 여도 아무 일도 하지 않는다
+             * (설정 창에서도 줄이 사라진다 — `keyboardNavWrap` 과 같은 방식).
+             *
+             * 끄고 싶을 만한 이유가 분명히 있다: 셸·에이전트 CLI 에서 `Ctrl+W` 는 **앞 단어
+             * 지우기**(0x17)다. 그걸 그대로 쓰려면 이 값만 끄면 되고, 목록 키보드 조작은 남는다.
+             * 켠 상태에서도 우리가 키를 먹는 것은 **닫을 탭이 실제로 정해졌을 때뿐**이다 —
+             * 그룹 헤더에 포커스가 있거나 설정 화면 입력창이면 키를 그대로 흘린다.
+             * 닫기는 사이드바 `✕` 와 같은 경로라(`closeTab(tab, true)`) 돌아가는 프로세스가
+             * 있으면 Tabby 가 평소처럼 한 번 물어본다.
+             */
+            keyboardCloseTab: boolean;
+            /**
+             * 줄을 끌어 순서를 바꾸는 동안 커서를 **목록 끝에 대면 목록이 따라 스크롤된다.**
+             *
+             * 기본으로 켠다 — 없으면 탭이 많아 목록이 넘치는 순간 "화면 밖으로 옮기기" 가
+             * 아예 불가능해진다(손을 떼고 스크롤한 뒤 다시 끄는 왕복이 필요하다). 그게
+             * 0.12.0 의 드래그 재정렬에 남아 있던 구멍이다.
+             *
+             * 끄면 0.12.0 과 똑같이 동작한다 — 목록은 가만히 있고, 보이는 줄 사이에서만
+             * 옮긴다. 자동 스크롤을 꺼서 얻는 것이 있다: 가장자리 띠 안에서 화면이 흐르지
+             * 않으므로 **맨 끝 줄의 뒤에 놓는** 조작이 절대 미끄러지지 않는다. 띠를 줄 하나
+             * 두께로 좁혀 두긴 했지만(deck.service `DRAG_SCROLL_BAND_PX`) 그 조작을 자주
+             * 하는 사람에게는 이 스위치가 답이다.
+             *
+             * 속도·띠 두께는 설정으로 내지 않았다 — px/s 는 사람이 판단할 수 있는 숫자가
+             * 아니고, 띠 두께는 줄 높이에서 나온 값인데 줄 높이가 설정이 아니다.
+             * 이 값은 **드래그 중에만** 읽는다: 끌지 않을 때는 커서가 목록 끝에 얹혀 있어도
+             * 아무 일도 일어나지 않는다(hover 리스너를 두지 않았다).
+             */
+            dragAutoScroll: boolean;
+            /**
+             * 사이드바 탭을 **작업 폴더(프로젝트) 단위로 묶고** 그룹 헤더로 접을 수 있게 한다.
+             *
+             * 기본으로 켠다 — 그룹이 하나뿐이면 헤더를 아예 그리지 않으므로(deck.service `render`)
+             * 한 프로젝트만 쓰는 사람에게는 0.6.0 까지와 화면이 똑같고, 탭이 열 개를 넘겨
+             * 여러 프로젝트가 섞이는 순간에만 헤더가 생긴다. 즉 켜 둬서 잃는 것이 없다.
+             * 묶는 기준은 **탭이 태어난 cwd** 다 — 셸에서 `cd` 를 해도 따라오지 않으므로
+             * (docs/DEVELOPMENT.md 0.5.0 실측) 세션이 사는 동안 그룹이 흔들리지 않는다.
+             * 그룹 안의 탭 순서는 `sortByStatus` 를 그대로 따른다.
+             */
+            groupByProject: boolean;
+            /**
+             * 프로젝트 경계의 기준 폴더. 비우면 `rootProfileCwd` 를 쓴다.
+             *
+             * 이게 필요한 이유 — cwd 를 그대로 키로 쓰면 `D:\Project\a` 에서 띄운 탭과
+             * `D:\Project\a\sub` 에서 띄운 탭이 다른 그룹으로 갈린다(서브폴더에서 에이전트를
+             * 띄우는 건 흔하다). 이 값을 `D:\Project` 로 채워 두면 그 **직하 한 단계**가 그룹이
+             * 되어 둘이 같은 그룹에 들어온다(`group.ts` `groupKeyOf`).
+             * 둘 다 비면 cwd 자체가 키다 — 프로젝트들이 한 상위 폴더에 모여 있지 않은 경우다.
+             * 저장소 루트(`.git`)를 찾아 자동으로 정하지는 않는다 — 렌더는 초당 여러 번 불리므로
+             * 그때마다 디스크를 훑을 수 없다.
+             */
+            groupRoot: string;
+            /**
+             * 접어 둔 그룹 키 목록. 그룹 헤더를 클릭할 때마다 갱신되고 다음 기동에 복원된다.
+             *
+             * 키는 `group.ts` 가 정규화한 경로를 **소문자로 접은** 값이다(`foldGroupKey`) —
+             * 셸이 알려주는 경로의 대소문자·구분자가 기동마다 달라도 접힘이 유지돼야 하기 때문이다.
+             */
+            collapsedGroups: any[];
             /**
              * 창이 가려져 있어도 사이드바를 계속 갱신한다 (Electron backgroundThrottling 해제).
              *
@@ -110,6 +311,18 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * 방향키는 핫키가 아니라서 xterm 이 조합을 먼저 확정하고 키를 보낸다.
              */
             releaseHomeEnd: boolean;
+            /**
+             * pty 에 바이트를 쓰기 전에 조합 중인 한글 음절을 먼저 확정시킨다.
+             *
+             * 핫키를 놓아주는 것(`releaseHomeEnd`)만으로는 부족했다 — 실사용 config.yaml 이
+             * 이미 `home: []` / `end: []` 인데도 조합 중 음절이 커서를 따라가는 증상이 재발했다
+             * (2026-09-08 사용자 재보고). 원인은 핫키가 아니라 **xterm 을 거치지 않는 pty 직접
+             * 쓰기**여서, 이 옵션은 그 쓰기 지점 전부를 한 진입점으로 모아 순서를 맞춘다
+             * (deck.service.ts `sendToPane` / `guardHomeEndComposition`, 기전은 `ime.ts`).
+             *
+             * false 로 두면 0.4.0 까지의 동작 그대로 — 조합 상태를 보지 않고 바로 쓴다.
+             */
+            imeOrderGuard: boolean;
             /**
              * 클립보드에 이미지만 있으면 Ctrl+V 로도 이미지가 들어가게 한다.
              *
@@ -224,6 +437,33 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * 항목 28 의 반전은 그 표본에는 해당하지 않았다.
              * 되살리려면 "앱이 pty 폭을 다시 읽게 만드는" 수단부터 찾을 것. 감지·채증(`screenWatch`)은 계속 돈다.
              */
+            /**
+             * **다시 켬 (2026-09-09).** 위 두 주석의 판단 근거가 오늘 채증으로 갈렸다.
+             *
+             * 껐던 이유는 "복구 수단이 이 유형에 안 듣는다" 였는데, 그 유형이 무엇이었는지가
+             * 오늘 실사용 8건으로 확정됐다 — **`xterm.cols != pty` 인 리사이즈 중간 프레임**이다
+             * (4건 전부, 0~3초 만에 스스로 복구, 화면 덤프는 앱 기준 정상). 거기에 `fit`+`nudge`
+             * 를 때렸으니 고쳐질 리가 없고 화면만 흔들렸다.
+             *
+             * 크기가 맞는데 깨진 나머지 4건(02:07:45~02:08:01, 자식 프로세스 stdout 이 TUI 를
+             * 덮어씀)은 26초를 버텼고, 이 유형은 `clearInputArea` + `Ctrl+L` 로 실제로 고쳐진다
+             * (회귀 PR8·PR9 가 격리 인스턴스에서 100~160ms 해소를 잰다).
+             *
+             * 그래서 **손댈 유형만 손대도록** `checkScreen` 에 크기 가드를 넣고 기본값을 켠다.
+             * 자동 경로가 하는 일은 사이드바 `↻` 한 번과 같다(잔상 지우기 + Ctrl+L, **흔들기 없음**).
+             *
+             * 켜기 직전에 "켜면 격리 인스턴스가 죽는다" 로 한 번 막혔는데, **그 죽음은 우리 코드가
+             * 아니었다** (2026-09-09 확정). `tools/test-instance.ps1 -Kill` 이 커맨드라인에
+             * `tabby-agentdeck-test` 가 든 Tabby 를 **전부** 죽이고 기동은 그 `ud` 폴더를 지운다 —
+             * 같은 저장소에서 두 세션이 동시에 회귀를 돌리면 서로의 인스턴스를 죽인다. 그때 CDP 는
+             * ECONNRESET 으로 끊기고 진단로그에 상대의 `setup start tabs=0` 이 이어 붙어 크래시처럼
+             * 보인다. 판별법 — **Crashpad 리포트가 비어 있으면 크래시가 아니라 누가 죽인 것이다**
+             * (`<ud>\Crashpad\reports`). 이름이 겹치지 않는 전용 인스턴스에서 다시 재니
+             * 기본 `true` 로 `probe-profile` 3회 연속 8 PASS / 0 FAIL 이었다.
+             *
+             * 끄고 싶으면 `%APPDATA%\tabby\config.yaml` 의 `agentDeck.autoRepairScreen: false`
+             * 한 줄이면 되고, 감지·채증(`screenWatch`)은 어느 쪽이든 돈다.
+             */
             autoRepairScreen: boolean;
             /**
              * 화면을 **보고 기록만** 한다 (복구는 하지 않는다).
@@ -318,6 +558,13 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
             sidebarWidth: number;
             /** 상/하 도킹일 때의 사이드바 높이 (px). 경계선 드래그로 바뀐다 */
             sidebarHeight: number;
+            /**
+             * 미리보기 패널이 붙는 방향 — 'right' | 'left'.
+             * 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥), 패널이 터미널 쪽(안)에 앉는다.
+             */
+            viewerDock: string;
+            /** 미리보기 패널 폭 (px). 경계선 드래그로 바뀐다 */
+            viewerWidth: number;
             /** 레이아웃/사이드바 전체 on-off */
             enabled: boolean;
             /** 터미널 뷰포트 가로:세로 비율 */
@@ -343,6 +590,17 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * 갈라야 하는데 순정 paste 는 텍스트만 알기 때문
              */
             'agentdeck-paste': string[];
+            /**
+             * 사이드바 목록에 키보드 포커스 (다시 누르면 터미널로 복귀).
+             *
+             * 기본값을 비워 두지 않은 이유 — 이것이 사이드바를 마우스 없이 만지는 **유일한
+             * 진입점**이라(목록은 tabindex=-1, `wireListKeys`) 안 묶여 있으면 기능이 없는 것과
+             * 같다. `Ctrl-Shift-L` 은 Tabby 순정 기본 핫키와 겹치지 않는다 — core·terminal·
+             * local·settings 네 패키지의 기본 조합을 훑어 확인했다(2026-09-09):
+             * 그쪽이 쓰는 것은 `Ctrl-Shift-{A,C,D,E,F,I,P,R,S,T,V,W,Z}`·방향키·Tab·PageUp/Down·
+             * Backspace·`-` 이다. 다른 플러그인과 부딪히면 설정 창에서 바꾼다.
+             */
+            'agentdeck-focus-list': string[];
         };
     };
 }