stackbite 0.5.31 → 0.5.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +325 -149
  2. package/package.json +25 -25
  3. package/packaging/npm/release.json +16 -16
package/README.md CHANGED
@@ -1,149 +1,325 @@
1
- # Stackbite through npm and npx
2
-
3
- Work Stack organizes the work. Stackbite gets it moving.
4
-
5
- Node.js 20 or newer is required. The portable runtime is available for Windows x64
6
- and Linux x64 with glibc 2.28 or newer; macOS, ARM and musl/Alpine builds are not supplied yet.
7
- The GNU Linux x86_64 runtime is built to target AlmaLinux 8 (glibc 2.28), so a
8
- newer host system glibc is not required. Node.js 20 or newer remains a separate
9
- prerequisite of the launcher itself.
10
- Python installation and compilation are unnecessary. Archive extraction requires
11
- `tar` (included in current Windows and common Linux distributions).
12
-
13
- ## Install without an account
14
-
15
- Choose one method. For a single run, use the public npm package:
16
-
17
- ```sh
18
- npx --yes stackbite
19
- ```
20
-
21
- For a persistent command, install it globally, prepare the runtime, then launch:
22
-
23
- ```sh
24
- npm install --global stackbite
25
- stackbite setup
26
- stackbite
27
- ```
28
-
29
- Global installation installs the small launcher without a postinstall download.
30
- `stackbite setup` downloads and fully validates its pinned runtime without starting
31
- the app or backend. It prints short stages to stderr. If setup is omitted, the
32
- first launch prepares the runtime with the same stages. Cached launches remain
33
- quiet and fully validate the runtime every time. Running both installation methods
34
- is unnecessary.
35
-
36
- The same preparation command works through npx:
37
-
38
- ```sh
39
- npx --yes stackbite setup
40
- ```
41
-
42
- Check a prepared runtime offline with `stackbite setup --check`. The launcher
43
- checks all pinned file hashes, identity, inventory and link boundaries, without
44
- downloading, extracting, writing cache files, or starting the app/backend. It exits
45
- with status 0 when valid and status 1 when absent or invalid; an absent cache needs
46
- `stackbite setup`. Only `setup` and `setup --check` are accepted setup forms.
47
- The launcher check is read-only; npx itself may install its npm package before
48
- invoking it, so use the installed command for an entirely offline check.
49
-
50
- Binary caches use `%LOCALAPPDATA%\Stackbite\cache` on Windows and
51
- `${XDG_CACHE_HOME:-~/.cache}/stackbite` on Linux. `LOCALAPPDATA`, `XDG_CACHE_HOME`
52
- and `HOME` overrides retain their normal behavior. These caches are separate from
53
- application state. Interrupted preparation removes only its own temporary staging
54
- directory and can be retried. An invalid existing runtime is reported and left in
55
- place; setup does not delete or overwrite it.
56
-
57
- Update a registry installation with `npm install --global stackbite@latest`.
58
-
59
- ## Direct GitHub package
60
-
61
- Run the package attached to the verified GitHub release:
62
-
63
- ```sh
64
- npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.31/stackbite-0.5.31.tgz
65
- ```
66
-
67
- Arguments go after the package URL, for example `--version` or `--status`. For a
68
- persistent command, install that same package globally:
69
-
70
- ```sh
71
- npm install --global https://github.com/Shinick-Han/stackbite/releases/download/v0.5.31/stackbite-0.5.31.tgz
72
- stackbite setup
73
- stackbite
74
- ```
75
-
76
- The core source repository remains private at `shinick-dev/stackbite`. The separate
77
- public `Shinick-Han/stackbite` repository distributes only this thin launcher and
78
- verified compiled runtime releases; installers need no GitHub or npm login.
79
- Registry-free distribution does not require publishing rights on npm.
80
- The small JavaScript package downloads the
81
- exact pinned native release on first execution, verifies its archive and file
82
- checksums and product identity, then reuses a persistent binary cache. There is no
83
- postinstall download or provider installation. An offline cached launch is possible;
84
- the first launch needs access to GitHub release downloads.
85
-
86
- For a GitHub URL installation, install the package URL from the newer release.
87
- Each npm package pins one native release; the portable app's own `stackbite update`
88
- does not change the npm package version.
89
-
90
- ## Existing data and processes
91
-
92
- `STACKBITE_STATE_DIR` is the explicit state override. The bundled native runtime
93
- owns state discovery and migration for both npm and direct launches. It reuses
94
- existing configured state and keeps live databases, authentication and records
95
- in place. New state uses `%LOCALAPPDATA%\Stackbite\state` or
96
- `${XDG_STATE_HOME:-~/.local/state}/stackbite`.
97
- Rooms, Seats, authentication, provider configuration, journals and Work Stack
98
- contracts are not renamed or migrated. Binary cache data is separate from this
99
- state. Installing or launching the npm package does not stop an existing backend.
100
- Check the connected server's capabilities before using newly added runtime features.
101
-
102
- For app commands, the launcher inherits terminal input/output and passes CLI
103
- arguments directly to the native app. Its `setup` command only prepares/checks the
104
- runtime. It does not insert a second screen renderer or an agent provider.
105
- Global npm installation creates only the `stackbite` command; it does not claim an
106
- external `helm` command or replace independent Kubernetes tooling.
107
-
108
- ## Maintainer release steps
109
-
110
- Measure bounded fake runtime preparation and warm verification without network or
111
- app processes:
112
-
113
- ```sh
114
- node packaging/npm/test/measure-setup.js
115
- ```
116
-
117
- The measurement reports fixture sizes and each preparation stage plus warm check
118
- and launch validation costs. It uses disposable cache data and an inert child
119
- stub; its timings are not measurements of released native bundles or providers.
120
-
121
- Build and verify both native platform archives first. Prepare the pinned manifest
122
- from their exact extracted bundles and archive bytes:
123
-
124
- ```sh
125
- python scripts/prepare_npm_release.py --version 0.5.30
126
- npm test
127
- npm pack
128
- ```
129
-
130
- Keep `package.json` and `packaging/npm/release.json` versions equal. Inspect `npm
131
- pack --dry-run` before publishing; the package must include the launcher and pinned
132
- manifest, and exclude native runtimes, installed state, credentials, tests and
133
- development worktrees. Test the packed package with `npx` on both platforms.
134
-
135
- Attach `stackbite-<version>.tgz` and its SHA-256 sidecar to the corresponding GitHub
136
- release in the public distribution repository. Copy only the npm file allowlist to
137
- that repository; never push the private core history, state, personal notes or
138
- credentials. Native archives must retain dependency license notices. Publishing
139
- the short name requires an authenticated owner account:
140
-
141
- ```sh
142
- npm login --registry=https://registry.npmjs.org
143
- npm publish --access public --registry=https://registry.npmjs.org
144
- ```
145
-
146
- Complete any registry-required authentication interactively; do not put credentials
147
- in this repository, prompts or package files. The repository currently specifies
148
- `UNLICENSED` for the JavaScript wrapper instead of inventing a license for the app;
149
- native runtime dependency notices remain in each platform archive.
1
+ # Stackbite: Local Multi-Agent Work App
2
+
3
+ > Work Stack organizes the work. Stackbite gets it moving.
4
+ >
5
+ > Work Stack으로 정리하고, Stackbite로 실행한다.
6
+
7
+ Stackbite는 Windows ConPTY와 Linux POSIX PTY를 사용하는 로컬 멀티 에이전트 작업 앱입니다.
8
+ Room에 작업 경로와 목표를 정하고, Seat에서 셸·Codex·Claude 같은 설치된 CLI를 병렬로
9
+ 실행합니다. TUI에서 방을 이동하거나 종료해도 데몬이 소유한 터미널은 계속 실행됩니다.
10
+ Work Stack 없이 사용할 수 있으며, Work Stack 연결은 Task 권한과 실행을 분리합니다.
11
+
12
+ ## 설치와 실행
13
+
14
+ 공개 [Stackbite 배포 저장소](https://github.com/Shinick-Han/stackbite/releases/tag/v0.5.29)의
15
+ 검증된 **0.5.29** 실행 파일과 TGZ는 GitHub 로그인 없이 받을 수 있습니다.
16
+ 0.5.29는 `701935da3dbc`에서 컴파일되었고, 이 소스 트리(`main`)의 빌드·런처 고정값은 0.5.26입니다.
17
+ 두 식별자의 구분은 [아키텍처 맵](ARCHITECTURE.md#build-and-release-identities)을 참고하세요.
18
+ 정식 제품명은 **Stackbite**, 명령어와 저장소 이름은 **`stackbite`**입니다.
19
+ 핵심 소스 저장소 [shinick-dev/stackbite](https://github.com/shinick-dev/stackbite)는 비공개로 유지합니다.
20
+
21
+ 0.5.20에는 간결한 Rust 화면이 포함됩니다. `stackbite --frontend rust`로 실행하고,
22
+ Alt+Shift+Z로 집중 화면, F6로 Seats 이동을 사용할 수 있습니다. 기존 키맵과 실행
23
+ 기본값은 유지됩니다. [Rust 화면과 실행 소유권 안내](docs/release-0.5.20.md)를 참고하세요.
24
+
25
+ ### npm / npx 설치
26
+
27
+ Node.js 20 이상과 `tar`가 있는 Windows x64 또는 glibc Linux x64에서 실행합니다.
28
+ Python 설치는 필요하지 않으며 첫 실행은 검증된 런타임을 내려받고 다음부터 캐시를 사용합니다.
29
+ 아래 두 방식 중 하나를 선택하면 됩니다. 전역 설치는 작은 런처를 설치하고,
30
+ 이어 `stackbite`를 처음 실행할 때 네이티브 런타임을 내려받습니다.
31
+
32
+ ```sh
33
+ npx --yes stackbite
34
+ ```
35
+
36
+ 계속 사용할 명령으로 설치하려면:
37
+
38
+ ```sh
39
+ npm install --global stackbite
40
+ stackbite
41
+ ```
42
+
43
+ [npm registry](https://www.npmjs.com/package/stackbite)의 공개 패키지를 사용합니다.
44
+ 특정 버전은 다음 GitHub TGZ URL로 지정할 수 있습니다.
45
+
46
+ ```sh
47
+ npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.18/stackbite-0.5.18.tgz
48
+ ```
49
+
50
+ macOS·ARM·Alpine은 현재 지원 대상이 아닙니다.
51
+ [런처 설치·업데이트 안내](packaging/npm/README.md)를 참고하세요.
52
+
53
+ ### 네이티브 실행 파일
54
+
55
+ Windows x64 ZIP의 **전체 압축을 해제한 뒤 `stackbite.exe`를 실행**합니다.
56
+ Linux x86_64 tar.gz는 전체를 해제하고 `./stackbite`를 실행합니다. 두 플랫폼 모두
57
+ `runtime/`을 실행 파일 옆에 유지하면 Python이나 소스 checkout 없이 동작합니다.
58
+ Linux의 최소 glibc 요구 사항은 `portable.json`의 `minimum_glibc`에 기록됩니다.
59
+
60
+ 선택적으로 Windows의 `install.cmd` 또는 Linux의 `./install.sh`로 사용자 계정에 설치합니다.
61
+ Codex·Claude 등 provider CLI의 설치와 로그인은 별도입니다.
62
+ 설치·롤백은 [Windows](packaging/README.md) / [Linux](packaging/linux/README.md) 안내를 따릅니다.
63
+
64
+ ```text
65
+ stackbite
66
+ stackbite --help
67
+ stackbite --version
68
+ stackbite --status
69
+ stackbite agent --help
70
+ stackbite update --check
71
+ ```
72
+
73
+ `--help`는 TUI나 백엔드를 시작하지 않습니다. `--version`은 실제 버전·커밋을,
74
+ `--status`는 실행·상태 경로를 확인하는 데 사용합니다. `stackbite update`는 배포 파일과
75
+ 체크섬을 검증하여 설치하며, 실행 중인 백엔드와 CLI를 종료하지 않습니다. 소스 checkout은
76
+ Git으로 업데이트합니다. 이미 실행 중인 백엔드는 기존 코드를 사용하므로 새 기능은 그
77
+ 백엔드를 명시적으로 재시작한 뒤 적용됩니다. 백엔드 재시작은 실행 중인 CLI를 종료합니다.
78
+
79
+ 0.5.18은 지원되는 로컬 백엔드와 지속적인 인증 연결로 입력을 전달하고, 변경된
80
+ 화면 행을 push로 받습니다. Windows PTY 수집은 출력 이벤트를 기다리며, 물리 셀
81
+ 렌더링에서는 출력만 바뀌면 기존 UI 프레임을 재사용합니다. 확대·축소, 스크롤,
82
+ 복사와 좌석 세대 검증을 유지하며, 기존 백엔드에는 HTTP 조회로 연결됩니다.
83
+ 실제 PTY 지연 측정의 범위와 한계는 `docs/terminal-stream-ui-1008.md`를 참고하세요.
84
+
85
+ 0.5.18은 단순 키 전달에 따른 불필요한 전체 화면 갱신을 줄이고, 검증된 불변
86
+ 화면 행을 재사용합니다. 한 좌석이 바쁜 동안 다른 좌석의 화면 발행을 계속하며,
87
+ 렌더 시간 자체를 갱신 간격에 포함합니다. 입력 ACK·실패 시 재전송 금지·좌석과
88
+ 화면 소유권 검증은 유지합니다. 이번 직렬 PTY 측정과 한계는
89
+ `docs/next-latency-release-1008.md`에 기록합니다.
90
+
91
+ 이하 기능·설정 안내는 공개된 **0.5.18** 기준입니다. 설치된 client/server의
92
+ 실제 버전과 지원 기능은 각각 확인하세요.
93
+
94
+ ### 오래된 VTE / Citrix 터미널
95
+
96
+ MATE Terminal의 VTE 0.52 환경에서 상태 원과 의자 glyph가 한 칸으로 표시되면,
97
+ 새 frontend를 다음처럼 실행합니다. csh/tcsh에서도 같은 명령을 사용합니다.
98
+
99
+ ```sh
100
+ env STACKBITE_CHROME_PROFILE=vte-0.52 ./stackbite
101
+ ```
102
+
103
+ 이 설정은 제품 UI의 두 glyph만 폭이 안정적인 표현으로 바꿉니다. 일반 터미널은
104
+ 기본 UI를 유지하며, Seat 출력·사용자 이름·폰트·터미널 설정은 바뀌지 않습니다.
105
+ 0.5.18는 지원되는 POSIX VT 터미널의 화면 행을 절대 위치로 출력하므로 raw tty의 LF 처리에 의존하지
106
+ 않습니다. frontend만 다시 열어도 표시 수정이 적용되며 기존 backend와 Seat를
107
+ 종료할 필요가 없습니다. [호환 설정과 검증 범위](docs/citrix-chrome-1008.md)를
108
+ 참고하세요.
109
+
110
+ ## Room과 Seat
111
+
112
+ 현재 소스는 연결된 백엔드에 방이 없으면 작업 폴더를 채운 Room 생성 화면을 엽니다.
113
+ Enter로 Room과 기본 shell을 열며, 같은 폴더에서 다시 실행하면 기억한 유효 Room으로 돌아갑니다.
114
+ 재접속만으로 중단된 Seat를 실행하지 않습니다. 다른 폴더·삭제된 Room이면 목록을 엽니다.
115
+ 작업실 백엔드가 꺼져 있으면 로컬 8090에서 시작합니다.
116
+ 방을 선택하고 Enter로 진입합니다. `F7` / `Alt+R`로 목록으로 돌아가며, 목록에서 `Esc`는
117
+ 이전에 열었던 작업실로 돌아갑니다. Room 생성 화면에서 Esc를 누르면 목록으로 돌아갑니다.
118
+ 목록 입력은 관리 동작이며 좌석의 CLI에 전달되지 않습니다.
119
+
120
+ 설정은 Room 생성 화면의 `Ctrl+D` 또는 Help의 `s`로 저장합니다. CLI에서는
121
+ `stackbite config set chrome_profile vte-0.52`, `stackbite config set terminal_core python`처럼
122
+ 한 번 저장하고 이후 `stackbite`만 실행하면 됩니다. 명시한 환경변수·실행 옵션은 저장값보다
123
+ 우선합니다. [첫 사용](docs/first-use.md), [설정](docs/launch-preferences.md),
124
+ [clone 후 단일 명령 빌드](docs/build-local.md), [Node 없는 설치](docs/install-from-release.md)를 참고하세요.
125
+
126
+ 화면 아래 `[+ Room]`, `[+ Terminal]`, `[Find seats]`로 방·터미널을 관리합니다.
127
+ 방에는 이름·작업 폴더·공통 목표를 지정합니다. Seat는 역할·개별 작업·범위·완료 조건·
128
+ 결과물·보고 대상을 가집니다. 이름을 바꿔도 내부 seat key와 실행 기록의 연결은 유지됩니다.
129
+ 검색은 여러 방의 이름·역할·명령·작업 경로를 찾고 `Tab`으로 상태를 필터링합니다.
130
+
131
+ 방 안에서 `Ctrl+T` / `Alt+T` 또는 `[+ New terminal]`을 선택하고 Enter를 누르면 기본 셸을
132
+ 엽니다. `codex`, `claude`, `python -i` 같은 설치된 명령과 인자도 입력할 수 있습니다.
133
+ 명령 선택창은 셸 연산자나 환경 변수를 자동 평가하지 않으므로 필요한 경우 셸 안에서 실행합니다.
134
+ 기존 터미널은 sidebar에서 클릭해 전환합니다.
135
+
136
+ `[Split →]` / `[Split ↓]`로 같은 방의 두 터미널을 표시합니다. pane 클릭은 입력 대상을
137
+ 바꾸고, 경계선 드래그는 크기를 조절합니다. `Alt+Z`는 현재 pane을 확대합니다.
138
+ 좌석·터미널 우클릭 또는 `Alt+M` / `Shift+F10`은 Rename, Close, Restart CLI 메뉴를 엽니다.
139
+ 좌석 패널의 `Delete`는 선택한 좌석을 닫고, 터미널 포커스의 `Delete`는 CLI에 전달됩니다.
140
+ 종료 동작은 선택한 generation만 대상으로 하며 기록은 보존합니다.
141
+
142
+ 꺼진 CLI 좌석을 선택하면 같은 좌석에 복구용 기본 셸을 엽니다. 원래 CLI 명령·모델·역할은
143
+ 유지하며 `Restart CLI`로 원래 명령을 다시 실행합니다. 이전 복구 요청의 전달 결과가
144
+ 불명확하면 먼저 그 요청을 조회합니다. 새 실행은 `Start new terminal (new request)` 또는
145
+ `Retry CLI (new request)`로 명시적으로 요청하며 이전 요청을 자동 재전송하지 않습니다.
146
+
147
+ 방 우클릭의 Archive / Restore / Delete room 또는 `/room-delete`로 방을 관리합니다.
148
+ 실행 중인 좌석이 있으면 먼저 명시적으로 종료해야 합니다. 삭제 확인창은 Cancel을 기본으로
149
+ 선택합니다. 정지된 활성 방은 확인 후 보관·삭제하며 작업 폴더·Git worktree·실행 기록은 보존합니다.
150
+ Restore는 좌석을 자동 실행하지 않습니다. `Ctrl+Q`는 TUI 연결만 해제합니다.
151
+
152
+ | 관리 명령 | 동작 |
153
+ | --- | --- |
154
+ | `/room-new 작업 이름` | 현재 작업 경로에 빈 작업실 생성; 자동 진입·실행 없음 |
155
+ | `/room <번호 또는 room_id>` | 작업실 선택 |
156
+ | `/seat-new qa powershell` | 선택 방에 좌석을 만들고 명시적으로 실행 |
157
+ | `/seat-add qa codex` | 정지된 좌석 정의만 추가 |
158
+ | `/room-run qa 검토해줘` | 정지된 provider 좌석에서 headless 단발 실행 |
159
+ | `/room-history`, `/room-context qa` | 실행 기록·초기 컨텍스트 확인 |
160
+ | `/room-find 검색어`, `/room-filter active` | 작업실 검색·상태 필터 |
161
+ | `/room-worktree 작업 이름` | Git 커밋 HEAD에서 별도 worktree 작업실 생성 |
162
+ | `/spawn qa codex`, `/kill qa` | 선택 방의 좌석 실행·종료 |
163
+ | `/broadcast 점검해줘` | 선택 방의 살아 있는 좌석에 지시 |
164
+ | `/archive`, `/restore` | 정지된 작업실 보관·복원 |
165
+
166
+ ## 터미널 입력과 출력
167
+
168
+ `Alt+H`로 검색 가능한 도움말을 엽니다. 도움말의 `Ctrl+P`로 관리 prefix를 활성화하고
169
+ `Ctrl+K`로 `Ctrl+B` / `Ctrl+A` / `Ctrl+Space` 중 선택합니다. prefix 뒤 `%` / `"`는
170
+ 좌우·상하 분할, `o`는 pane 전환, `n`은 좌석 검색, `[`는 복사 모드입니다.
171
+ 같은 prefix를 두 번 누르면 문자 하나를 CLI에 전달합니다. 도움말의 `Ctrl+L`로 관리
172
+ 단축키를 해제하면 해당 키를 CLI에 전달할 수 있습니다.
173
+
174
+ 출력 드래그는 선택 후 버튼을 놓으면 복사합니다. CLI가 마우스 입력을 요청하면 휠·왼쪽
175
+ 클릭은 포인터 아래 CLI에 전달하며, `Shift`를 누른 드래그는 Stackbite 출력 선택입니다.
176
+ `Shift`+휠은 Stackbite 이력을 탐색합니다. 메뉴나 출력 선택 중에는 CLI에 마우스를 보내지 않습니다.
177
+ CLI 포인터 입력에는 백엔드의 `terminal_mouse`와 `terminal_geometry`가 모두 필요합니다.
178
+ 실제 PTY 크기·화면 원점·좌석 generation이 확인된 라이브 화면에서만 좌표를 전달합니다.
179
+ 오래된 백엔드에서는 안내에 따라 업데이트·재시작합니다.
180
+ [터미널 입력·크기 계약](docs/terminal-interaction-contract.md)에 자세한 규약이 있습니다.
181
+
182
+ `Shift+PageUp` / `Shift+PageDown`은 이력을 탐색하고 `End`는 라이브 화면으로 돌아갑니다.
183
+ 분할 pane은 각자 이력 위치를 유지합니다. 보관량은 좌석마다 기본 2,000줄이며
184
+ 백엔드 시작 전에 `STACKBITE_SCROLLBACK_LINES`로 1~20,000줄을 지정합니다.
185
+ 잘못된 값은 기본값으로 돌아갑니다. 오래된 줄부터 제거하며 보관량을 늘리면 메모리도 늘어납니다.
186
+ 이력은 메모리이므로 백엔드 재시작 시 초기화됩니다.
187
+
188
+ `Alt+C` 또는 prefix + `[`로 복사 모드를 열어 `/` 검색, `n` / `N` 다음·이전 결과,
189
+ `v` 선택, 방향키 이동, `y` 복사를 사용합니다. `Esc`로 돌아갑니다.
190
+ Windows는 시스템 클립보드를, Linux는 `Ctrl+O` 또는 `STACKBITE_CLIPBOARD_OSC52=1`로
191
+ 명시적으로 허용한 OSC52를 사용합니다. 호스트 터미널의 OSC52 지원이 필요합니다.
192
+
193
+ 터미널은 전경색·배경색·문자 속성과 결합 문자·이모지의 셀 폭을 보존합니다.
194
+ 대체 화면의 짧은 출력 묶음과 DEC2026 동기화 구간은 표시 프레임을 합치지만 모든 바이트는
195
+ 즉시 파싱합니다. 실행 완료는 표시 지연과 별개이며 모든 CLI 재도색을 완전히 재현하는 것은 아닙니다.
196
+ 실제 PTY 기본 환경은 `TERM=xterm-256color`, `COLORTERM=truecolor`입니다.
197
+ 호출자가 좌석 환경에 명시한 `NO_COLOR`, `TERM`, `COLORTERM`은 보존합니다.
198
+
199
+ ## 에이전트 협업과 API
200
+
201
+ 좌석 안에서는 `stackbite-room`으로 같은 방의 동료를 관리합니다.
202
+
203
+ ```text
204
+ stackbite-room context
205
+ stackbite-room ready
206
+ stackbite-room summon reviewer --provider codex --task-file review-task.txt --scope src --acceptance "tests pass" --output-path review.md --report-to coordinator
207
+ stackbite-room send reviewer --prompt-file followup.txt
208
+ stackbite-room wait reviewer --generation RECEIPT_GENERATION --turn 4 --timeout 30
209
+ stackbite-room read reviewer
210
+ stackbite-room report --state progress --message "검토 중" --artifact review.md
211
+ stackbite-room inbox
212
+ ```
213
+
214
+ `assign`은 작업 메타데이터를 바꾸고 `send`는 실제 지시를 제출합니다. 여러 지시는 같은
215
+ 프로세스·대화에 전달됩니다. 바쁜 좌석·사용자 입력 초안·교체된 generation에는 지시를
216
+ 거절하며 자동 재전송하지 않습니다. `report --state completed`는 에이전트 보고로 보존하며
217
+ provider 완료 증거와 구별합니다. Codex·Claude의 hooks는 시작·작업·승인 대기·응답 완료를
218
+ 기록합니다. CLI 로그인, workspace 신뢰, hooks 신뢰와 도구 실행 승인은 provider 안에서 처리합니다.
219
+ Stackbite는 승인·sandbox를 우회하지 않습니다.
220
+
221
+ Python SDK `AgentStackbite`는 방을 대상으로 합니다. 외부 스크립트는 `room_id`를
222
+ 명시하고, 좌석 안의 에이전트는 상속된 `STACKBITE_ROOM_ID`를 사용합니다. 인증된
223
+ `TaskRoomClient`로 위임하며 방이 없는 호출은 거절합니다. 직접 방 API를 사용하려면
224
+ `TaskRoomClient`를 사용합니다.
225
+
226
+ 기존 방의 좌석을 조회하는 예:
227
+
228
+ ```python
229
+ from private_pty import AgentStackbite, TaskRoomClient
230
+
231
+ sdk = AgentStackbite(room_id="review-room", client=TaskRoomClient())
232
+ seats = sdk.list_agents() # 이 방의 정의된 좌석; 정지된 좌석도 포함
233
+ ```
234
+
235
+ 좌석 안에서는 `AgentStackbite()`가 상속된 방을 사용합니다. 생성자는 데몬을 시작하거나
236
+ 로컬 에이전트를 생성하지 않습니다.
237
+
238
+ 기본 방 주소는 `http://127.0.0.1:8090`입니다. 명시적 `base_url`,
239
+ `STACKBITE_ROOM_BRIDGE_URL`, 기본 주소 순서로 선택합니다. 클라이언트는 상태 위치에서
240
+ 기존 인증 토큰을 읽어 `X-Office-Token`으로 전송합니다. 토큰 값을 프롬프트나 로그에 넣지 않습니다.
241
+
242
+ ```python
243
+ from private_pty import TaskRoomClient
244
+
245
+ client = TaskRoomClient()
246
+ room = client.create_worktree_room(
247
+ "입력 안정화", source_repo=r"C:\my-project",
248
+ objective="입력 회귀를 수정하고 테스트 결과를 보고한다",
249
+ )
250
+ rid = room["room_id"]
251
+ client.add_seat(rid, "qa", agent_kind="codex", role_title="회귀 검토")
252
+ result = client.run(rid, "qa", "입력 처리를 검토하고 결함을 보고해줘",
253
+ request_id="input-review-001", timeout=120)
254
+ history = client.executions(rid)
255
+ ```
256
+
257
+ `run()`은 정지된 좌석의 명시적인 headless 단발 실행입니다. 대화형 `spawn` / `send`가
258
+ 실패해도 headless 실행으로 바꾸지 않습니다. `dispatch()`는 살아 있는 대화형 CLI에
259
+ generation을 확인한 뒤 입력합니다. 지시별 request ID·generation·turn receipt로
260
+ 전달과 완료를 구별합니다. 같은 ID·지시는 저장된 receipt를 반환하고 다른 지시는 충돌합니다.
261
+ 불명확한 전달은 `unknown_delivery`로 보고하며 자동 재실행하지 않습니다.
262
+
263
+ 완료는 owned process와 provider의 명시적 lifecycle 증거로 판정합니다. 잠깐의 출력 정지나
264
+ CLI 종료 코드 0만으로 AI 작업 성공을 판정하지 않습니다. blocked는 개입이 필요한 상태입니다.
265
+ 결과물 등록·accepted/rejected 검토·외부 Task 완료는 각각 별도 동작입니다.
266
+
267
+ 실행 저널은 지시·generation·turn·상태·완료 근거·최대 64 Ki 문자의 출력 스냅샷을 저장합니다.
268
+ 모든 키 입력을 기록하는 transcript는 아닙니다. 백엔드 재시작은 셸 메모리를 복구하지 않으며
269
+ 살아 있는 generation이 없는 미완료 실행은 interrupted로 표시합니다.
270
+ Windows 네이티브 실행은 전용 Job Object가 provider와 그 자식 프로세스를 소유합니다.
271
+
272
+ ## 데이터와 Work Stack
273
+
274
+ 새 설치는 Stackbite 이름의 경로를 사용합니다. 이전 설치의 실제 DB·토큰·설정은 상태
275
+ locator(`.stackbite-state.json`)와 파일 매핑으로 **현재 위치에서 재사용**합니다. 열려 있는 SQLite DB를 복사하거나
276
+ 이름을 바꾸지 않습니다. 이전 제품명 경로가 실제 데이터 위치로 남아 있어도 추가 상태
277
+ 트리를 만들 필요가 없습니다. 0.5.18의 `stackbite --status`는 실제 `state`와 인증 파일의
278
+ `auth_file` 경로를 반환합니다. 인증 파일은 그 경로를 사용하며, 상태 폴더 아래 고정된
279
+ 새 파일명으로 추측하거나 별도 토큰을 만들지 않습니다. 토큰 내용은 출력하지 않습니다.
280
+ [호환성 안내](docs/stackbite-compatibility.md)에 durable data와 인증 경계가 있습니다.
281
+
282
+ Work Stack은 작업 정리와 Task 권한을, Stackbite는 로컬 Room/Seat 실행을 담당합니다.
283
+ 연결 개발은 `integration/work-stack`에서 분리하고 병렬 실행·우선순위·의존성 기반 선택을
284
+ 유지합니다. 선택한 Task의 workspace·revision을 확인한 뒤 방을 만들며 이 과정은 Task
285
+ 상태를 수정하지 않습니다.
286
+
287
+ ```powershell
288
+ python -m private_pty.workstack_link room --task T-0041 --cwd C:\my-project --isolated --source-repo C:\my-project
289
+ ```
290
+
291
+ handoff의 첫 줄 `WorkStack binding:` JSON marker와 Task ID·workspace·revision 계약은
292
+ 유지합니다. `publish_checkpoint()`는 새로 검증한 바인딩과 안정적인 intent ID로 호출자가
293
+ 작성한 사실만 전달합니다. commit_unknown은 operation-status로 확인하고 mutation을
294
+ 재전송하지 않습니다. 로그·프롬프트 자동 복사나 Task 자동 완료는 하지 않습니다.
295
+
296
+ 초기 에이전트 컨텍스트에는 실제 cwd/worktree, 사용 가능한 CLI와 비밀값을 노출하지 않는
297
+ 인증 API 사용법을 포함하며 다음 소개를 전달합니다.
298
+
299
+ > Stackbite는 현재 로컬에서 실행 중인 자체 멀티 에이전트 작업 앱이다.
300
+
301
+ ## 개발과 성능 검토
302
+
303
+ ```powershell
304
+ python -m pip install -r requirements-build.txt
305
+ python stackbite.py
306
+ ```
307
+
308
+ 핵심 구현은 `private_pty/`의 PTY·VT 버퍼·세션 registry·Room/Seat·실행 저널·Rich TUI와
309
+ `office_backend_bridge.py`의 인증 HTTP API입니다. 런타임 데이터와 개인 설정은 배포에 포함하지
310
+ 않습니다. 별도 웹 UI는 `/stackbite/company_office_mockup.html`이며 `/agency-agents/`의
311
+ manifest identity는 유지합니다.
312
+ 원격 웹 접속의 origin·신뢰 프록시는 `STACKBITE_ALLOWED_ORIGINS`·`STACKBITE_TRUSTED_PROXY_IPS`로
313
+ 명시합니다. `X-Office-Token` 인증은 로컬 요청에도 필요합니다.
314
+
315
+ 변경·검증·통합 경계는 [CONTRIBUTING.md](CONTRIBUTING.md)를 따릅니다.
316
+ 실제 provider 테스트는 별도 opt-in이며 사용자 상태·진행 중인 좌석에서 실행하지 않습니다.
317
+
318
+ [최적화 후보](docs/optimization-candidates.md)는 우선순위·소스 근거·위험·검증을 정리합니다.
319
+ [기존 측정 보고서](docs/optimization/implementation-results-059.md)는 일부 렌더링·본문·저장소
320
+ 개선과 함께 HTTP 서버 CPU 증가·일부 VT 재생 시간 증가를 기록합니다. 앱 전체가 빨라졌다고
321
+ 주장하지 않습니다.
322
+
323
+ ## License
324
+
325
+ Private & Proprietary — All Rights Reserved.
package/package.json CHANGED
@@ -1,25 +1,25 @@
1
- {
2
- "name": "stackbite",
3
- "version": "0.5.31",
4
- "description": "Verified native Stackbite CLI bootstrapper",
5
- "license": "UNLICENSED",
6
- "engines": {
7
- "node": ">=20"
8
- },
9
- "bin": {
10
- "stackbite": "packaging/npm/bin/stackbite.js"
11
- },
12
- "files": [
13
- "packaging/npm/bin/",
14
- "packaging/npm/lib/",
15
- "packaging/npm/release.json"
16
- ],
17
- "scripts": {
18
- "test": "node --test packaging/npm/test/*.test.js"
19
- },
20
- "repository": {
21
- "type": "git",
22
- "url": "https://github.com/Shinick-Han/stackbite.git"
23
- },
24
- "homepage": "https://github.com/Shinick-Han/stackbite"
25
- }
1
+ {
2
+ "name": "stackbite",
3
+ "version": "0.5.32",
4
+ "description": "Verified native Stackbite CLI bootstrapper",
5
+ "license": "UNLICENSED",
6
+ "engines": {
7
+ "node": ">=20"
8
+ },
9
+ "bin": {
10
+ "stackbite": "packaging/npm/bin/stackbite.js"
11
+ },
12
+ "files": [
13
+ "packaging/npm/bin/",
14
+ "packaging/npm/lib/",
15
+ "packaging/npm/release.json"
16
+ ],
17
+ "scripts": {
18
+ "test": "node --test packaging/npm/test/*.test.js"
19
+ },
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "https://github.com/Shinick-Han/stackbite.git"
23
+ },
24
+ "homepage": "https://github.com/Shinick-Han/stackbite"
25
+ }
package/packaging/npm/release.json CHANGED
@@ -1,26 +1,26 @@
1
1
  {
2
2
  "schema": 1,
3
- "version": "0.5.31",
4
- "commit": "74b37f10eda41d7306efd7fce9d2b10d74432d7e",
3
+ "version": "0.5.32",
4
+ "commit": "759b10500a81532aafb7ef07e6b4e27380e618a5",
5
5
  "repository": "Shinick-Han/stackbite",
6
6
  "platforms": {
7
7
  "win32-x64": {
8
- "asset": "stackbite-0.5.31-windows-x64-74b37f10eda4.zip",
9
- "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.31/stackbite-0.5.31-windows-x64-74b37f10eda4.zip",
10
- "sha256": "556743b7dfbbbcc4c7399e6772ffb54aa2fcf48464df2e133a858bb6bc1e17f6",
11
- "size": 44172522,
12
- "root": "stackbite-0.5.31-windows-x64-74b37f10eda4",
13
- "manifestSha256": "9a5a1207ced66562ec956a87b3c8e51a9598881b8707f4bb44ff6e4cbc3134d0",
14
- "metadataSha256": "4187607cbe38ec07ead29b28c4ce927f249777c0e0f2961b2d512a6f1ad16238"
8
+ "asset": "stackbite-0.5.32-windows-x64-759b10500a81.zip",
9
+ "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.32/stackbite-0.5.32-windows-x64-759b10500a81.zip",
10
+ "sha256": "db501303b80c2013afc692a19e9c9e1210d727e5dd630d66f9e6fccc7ebae4ef",
11
+ "size": 44186073,
12
+ "root": "stackbite-0.5.32-windows-x64-759b10500a81",
13
+ "manifestSha256": "90ea028ee0de564dea1e0b4fae32a46dd7a5747e05a64cda8636e3f9b4658758",
14
+ "metadataSha256": "f2c5944b1557cb2d9a0e262ab7854d91a0ac09c5a95a77a92a4b98fe87e7e609"
15
15
  },
16
16
  "linux-x64": {
17
- "asset": "stackbite-0.5.31-linux-x86_64-74b37f10eda4.tar.gz",
18
- "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.31/stackbite-0.5.31-linux-x86_64-74b37f10eda4.tar.gz",
19
- "sha256": "c1dc04cf0ab889c32fb10dbb5bd0e3c277ebf5caa570493519feac02c3c3c2c3",
20
- "size": 31100533,
21
- "root": "stackbite-0.5.31-linux-x86_64-74b37f10eda4",
22
- "manifestSha256": "ad294a04311c82e7a01167396399b7216654978b205848a6a5a49a452022842b",
23
- "metadataSha256": "1ebb8763041be215c8233b263ce01e1894521711e5f17f0d99e478cac0616398"
17
+ "asset": "stackbite-0.5.32-linux-x86_64-759b10500a81.tar.gz",
18
+ "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.32/stackbite-0.5.32-linux-x86_64-759b10500a81.tar.gz",
19
+ "sha256": "371689ab5927a07ffcc15de87851fb3fa9103362cc722dd9a106e3d83018eafe",
20
+ "size": 31113112,
21
+ "root": "stackbite-0.5.32-linux-x86_64-759b10500a81",
22
+ "manifestSha256": "9c6f55da6e67af201118c65a99bb1ba77ff81fc63158b554fdfad3717acb5766",
23
+ "metadataSha256": "7b19612a7ea3431de61632f232f1fe9231221005e1691bce2310144d1c5df745"
24
24
  }
25
25
  }
26
26
  }