codex-agent-view 0.4.1 → 0.4.3

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 (13) hide show
  1. package/.codex-plugin/plugin.json +2 -2
  2. package/README.ko.md +32 -24
  3. package/README.md +31 -23
  4. package/bin/codex-agent-view.mjs +63 -1
  5. package/package.json +1 -1
  6. package/public/app.js +246 -46
  7. package/public/index.html +16 -16
  8. package/public/styles.css +49 -8
  9. package/scripts/auto-start-monitor.mjs +10 -2
  10. package/skills/show-agents/SKILL.md +28 -16
  11. package/skills/show-agents/agents/openai.yaml +1 -1
  12. package/src/runtime/config.mjs +131 -0
  13. package/src/runtime/server.mjs +14 -5
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-agent-view",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "Read-only Codex app task snapshots with a trusted-hook auto-prepared local live backend.",
5
5
  "author": {
6
6
  "name": "Junho Yoon",
@@ -27,7 +27,7 @@
27
27
  "privacyPolicyURL": "https://github.com/JunhoYoon95/codex-agent-view/blob/main/docs/privacy.md",
28
28
  "termsOfServiceURL": "https://github.com/JunhoYoon95/codex-agent-view/blob/main/docs/terms.md",
29
29
  "defaultPrompt": [
30
- "Open @ and select the bundled Show Agents skill."
30
+ "$show-agents"
31
31
  ]
32
32
  }
33
33
  }
package/README.ko.md CHANGED
@@ -10,10 +10,10 @@ Codex Agent View는 공식 Codex 앱 안에서 여러 workspace의 active task
10
10
 
11
11
  ### 빠른 시작: 설치 후에는 Codex 앱 안에서만 사용
12
12
 
13
- 이 README는 exact `codex-agent-view@0.4.1` release를 설명한다. **최초 설치만** 일반 터미널에서 아래 exact-version 명령으로 진행한다. npm이 이 version을 찾지 못하면 `0.4.1` registry publish가 완료됐는지 확인한 뒤 다시 시도한다.
13
+ 이 README는 아직 배포되지 않은 `codex-agent-view@0.4.3` release candidate를 설명한다. **최초 설치만** `0.4.3`이 registry에 나타난 뒤 일반 터미널에서 아래 exact-version 명령으로 진행한다. 현재 public npm `latest`는 `0.4.2`다.
14
14
 
15
15
  ```bash
16
- npm install --global codex-agent-view@0.4.1
16
+ npm install --global codex-agent-view@0.4.3
17
17
  codex-agent-view install
18
18
  ```
19
19
 
@@ -25,20 +25,20 @@ codex-agent-view install
25
25
  2. Codex 앱의 **Plugins** 화면에서 `Codex Agent View`가 설치·활성화됐는지 확인한다.
26
26
  3. Hook 검토 화면이 표시되면 `hooks/hooks.json`과 `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command를 확인하고 현재 definition을 직접 trust한다. 앱 버전이 hook 검토 UI를 제공하지 않을 때만 설치 과정의 일부로 interactive Codex CLI의 `/hooks`를 사용한다.
27
27
  4. 활성화와 hook 검토를 마친 뒤 Codex 앱에서 **새 task**를 만든다. 설치 전에 시작된 task의 과거 event는 재생되지 않는다.
28
- 5. 새 task의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택한다.
29
- 6. Live 화면을 닫았다면 같은 `@` picker에서 **Show Agents**를 다시 직접 선택해 재오픈한다.
28
+ 5. Plugin 카드의 **지금 사용해보기**를 누른다. Starter `$show-agents`가 Codex 앱 task에서 bundled **Show Agents** skill을 명시적으로 호출한다.
29
+ 6. Live 화면을 닫았다면 Codex 앱 task에 `@codex-agent-view $show-agents`를 입력해 같은 bundled skill을 다시 호출한다.
30
30
 
31
- Plugin 카드의 **바로 사용하기** 버튼은 `Open @ and select the bundled Show Agents skill.`이라는 안내 text만 입력한다. 이 text 자체는 skill을 호출하지 않는다. 안내에 따라 `@` picker를 열고 bundled **Show Agents** skill 자체를 직접 선택한다. `$show-agents`는 Codex 앱 GUI의 지원 사용법이 아니다.
31
+ Plugin 카드의 **지금 사용해보기**와 수동 composer 입력 `@codex-agent-view $show-agents`는 둘 다 명시적인 앱 내 skill 호출이다. 사용자에게 terminal command, 외부 browser 또는 localhost URL 관리를 요구하지 않는다.
32
32
 
33
33
  Trust된 첫 hook이 도착하면 plugin sender가 로컬 backend를 내부적으로 준비하고 같은 event 전달을 재시도한다. 사용자는 task ID를 등록하거나 `start`, `status`, `doctor`를 실행할 필요가 없다. **Show Agents**는 healthy backend를 재사용하고 Codex 앱 안에서 live 화면 열기를 시도한다. 앱이 필요한 Browser capability를 제공하지 않거나 permission이 허용되지 않으면 private URL을 노출하는 대신 화면을 열 수 없다고 안내한다. Tokenized localhost URL은 대화에 노출하지 않으며 외부 browser도 정상 사용 흐름에 포함되지 않는다.
34
34
 
35
- 공개 Codex plugin API에는 prompt 없이 앱 시작과 동시에 sidebar, panel 또는 Browser tab을 생성하는 기능이 없다. 따라서 live 화면을 처음 열 때 Codex 앱 task에서 **Show Agents**를 한 번 명시적으로 선택해야 한다. 이미 오른쪽에 열린 live tab은 같은 monitor 관찰 window 동안 2초마다 자동 갱신하고 일시 연결 단절 뒤에도 기존 token으로 재연결한다.
35
+ 공개 Codex plugin API에는 prompt 없이 앱 시작과 동시에 sidebar, panel 또는 Browser tab을 생성하는 기능이 없다. 따라서 live 화면을 열 때 plugin 카드의 **지금 사용해보기** 또는 Codex 앱 task의 `@codex-agent-view $show-agents`를 사용한다. 이미 오른쪽에 열린 live tab은 2초마다 자동 갱신하고, backend가 같은 loopback origin으로 돌아오면 일시 연결 단절·monitor 재시작·package upgrade 뒤에도 자동 재연결한다. Monitor가 재시작되면 live 관찰 window는 새로 시작하며 read-only viewer credential만 유지된다.
36
36
 
37
37
  요약하면 설치는 터미널에서 한 번, 조회·상태 확인·live 화면 열기와 이후 사용은 Codex 앱 안에서 수행한다.
38
38
 
39
39
  ### 현재 상태
40
40
 
41
- 이 repository와 package의 version은 `0.4.1`이다. 다음 구성이 package에 포함되어 있다.
41
+ 이 repository와 package는 아직 배포되지 않은 `0.4.3` release candidate다. 2026-08-02 registry 확인 기준 public npm `latest`는 `0.4.2`다. Candidate에는 다음 구성이 포함되어 있다.
42
42
 
43
43
  - 공식 Codex 앱의 내장 thread tools를 우선 사용하는 app-native active-task snapshot skill
44
44
  - `.codex-plugin/plugin.json`, local marketplace catalog, genuine Codex skill
@@ -72,15 +72,23 @@ Maintainer npm 2FA는 `auth-and-writes` mode로 활성화됐고 `codex-agent-vie
72
72
 
73
73
  `0.4.0` known issue: manifest의 `defaultPrompt: ["Show Agents"]`는 평문 plugin-level text starter였다. 이 text는 implicit invocation이 disabled된 `show-agents` skill을 명시적으로 호출하지 않으므로 plugin 카드나 **바로 사용하기** 동작 자체를 skill 실행으로 취급한 안내는 잘못이었다. `0.4.1`은 이를 `Open @ and select the bundled Show Agents skill.`이라는 instructional starter로 교체했다. Starter는 여전히 호출이 아니라 안내이며, 일반 사용의 유일한 canonical 실행 경로는 새 task의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택하는 것이다. `0.4.1` public registry나 exact app E2E evidence는 별도로 검증해 기록한 범위에서만 주장한다.
74
74
 
75
+ 공개 `0.4.1`: npm `latest`/version, Apache-2.0 license, executable mapping, registry signature, 25 files, package size `53650 B`, unpacked size `193424 B`, shasum `ee2ae0b8b36016f5c57bade067027202b1508d1d`, integrity `sha512-WC4f5MPmvpkXeKM+1BVAYqW4+hoaUrB4yQFoUYgc0pnjyY7hP1CdSR5NJ3QWmvJ6Ikmmb1d+58UL4hkKoyhm1Q==`를 확인했다. Release tarball과 registry tarball은 byte-identical이다. Exact tarball publish로 npm metadata에 `gitHead`가 없으므로 그 field를 통한 source 일치는 주장하지 않는다. Annotated `v0.4.1` tag는 commit `a1de67be5413fa38b8dd1b62f74353463f6e641e`을 가리키며 [GitHub Release v0.4.1](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.4.1), main CI run `30710490358`, tag CI run `30710848474`가 공개·성공했다. 이 기기의 CLI/plugin은 `0.4.1`로 일치하고 plugin installed/enabled 및 hook wiring 9종을 확인했다. Runtime은 install 교체 중 정상 종료돼 현재 `monitor_not_running`이고 persisted hook trust는 `unknown`이다. Codex 앱 process가 설치 전부터 열려 있었으므로 앱 완전 재시작/new task 전까지 direct **Show Agents** visual E2E는 미확인이다.
76
+
77
+ 공개 `0.4.2`는 plugin starter를 `$show-agents`로 바꿔 plugin 카드에서 bundled **Show Agents** skill을 명시 호출하며, `@codex-agent-view $show-agents`를 수동 앱 내 재오픈 경로로 제공한다. Release commit `b4d923a`와 `3d8f46d`를 push했고 main CI run `30712375726`이 Node.js 18/20/22에서 통과했다. npm publish 뒤 `latest: 0.4.2`, Apache-2.0, 예상 executable mapping, 25 files, registry signature, shasum `fac95689395baa26f4ad9ff0cbefd0017d2ebd8d`, integrity `sha512-FRTPoYxjBuPC6Usb+ylSfZsZVJKlKcHnQPaAPljekg0maTPn9POsBkS+auOcHz5jspg0AXcP8R63PM0WfCn2LQ==`를 확인했다. Release/registry tarball은 byte-identical이고 annotated `v0.4.2` tag와 [GitHub Release v0.4.2](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.4.2)가 공개됐다. 이 기기의 exact global install, plugin installed/enabled, hook wiring 9종, installed artifact 일치와 공식 Codex in-app Browser visual E2E도 확인했다.
78
+
79
+ 아직 배포되지 않은 `0.4.3` candidate는 기존 앱 전용 사용 흐름을 유지하면서 live 화면 인증을 runtime 제어 권한에서 분리한다. 사용자 전용 private viewer credential은 설치 수명 동안 유지되고 `/api/state` 읽기만 허용한다. Hook event ingest와 shutdown에 사용하는 runtime/control token은 별도이며 monitor process와 함께 교체된다. `0.4.2`에서 upgrade할 때 viewer credential이 아직 없고 legacy runtime record가 유효하면 기존 token으로 viewer credential을 seed하되 값을 출력하지 않는다. 따라서 이미 열린 Codex live tab은 같은 loopback origin에서 backend가 다시 시작되면 재연결할 수 있다. 다만 task/event state는 계속 process-local bounded memory뿐이므로 monitor restart 뒤에는 빈 새 관찰 window가 시작된다.
80
+
75
81
  ### 제품 경계
76
82
 
77
83
  Codex Agent View는 historical audit이나 session replay 제품이 아니라 현재 활동을 보여주는 live companion이다. Bounded in-memory state와 monitor 재시작 시 reset은 privacy와 단순한 failure boundary를 위한 의도된 완성 설계다. SQLite/영구 history는 누락된 요구사항이 아니다. 실제 사용자 요구가 입증될 때에만 retention, migration, deletion, privacy 비용을 별도 검토하는 명시적 opt-in 기능 후보로 취급한다.
78
84
 
79
85
  - 앱 안의 현재 task snapshot은 공식 Codex 앱이 제공하는 내장 thread tools의 explicit status와 `subAgentActivity`를 우선 사용한다.
80
- - Hook event는 local monitor의 세부 lifecycle 상태에 대한 source of truth다. Monitor state는 bounded memory에만 있고 재시작하면 새 관찰 window가 시작된다.
86
+ - Hook event는 local monitor의 세부 lifecycle 상태에 대한 source of truth다. Monitor state는 bounded memory에만 있고 재시작하면 새 관찰 window가 시작된다. 별도 private viewer credential은 task history가 아니라 인증 metadata다.
87
+ - Read-only viewer credential은 한 설치 수명 동안 monitor 재시작과 upgrade를 넘어 유지되며, runtime/control token은 별도 process-scoped credential이다.
81
88
  - 설치·trust·앱 재시작 뒤 첫 trusted hook이 backend를 자동 준비한다. 이는 monitor process 준비이며 Codex 화면이나 tab을 몰래 생성하는 기능이 아니다.
82
89
  - 외부 telemetry, 원격 server, account, 필수 SQLite/영구 event store가 없다.
83
90
  - prompt, transcript path, 전체 tool input/output, assistant message를 monitor 상태나 UI에 저장·표시하지 않는다.
91
+ - 기본 monitor는 실행 중인 부모 task와 subagent를 먼저 정렬하고 사람이 읽을 수 있는 label/status를 우선하며, raw ID와 event name은 주 정보로 표시하지 않는다.
84
92
  - task/subagent 중지·재시작, message 전송, permission 자동 승인·거절 기능이 없다.
85
93
  - 별도로 실행한 App Server는 앱 내장 thread tools와 다른 process다. 공식 앱의 live source로 간주하거나 둘을 같은 API로 설명하지 않는다.
86
94
 
@@ -88,10 +96,10 @@ Codex Agent View는 historical audit이나 session replay 제품이 아니라
88
96
 
89
97
  ### npm, Codex 앱 live view, Plugins Directory의 역할
90
98
 
91
- - 공식 Codex 앱의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택하는 것이 canonical UX다. 별도 monitor 실행이나 task ID 등록이 필요 없다.
99
+ - Plugin 카드의 **지금 사용해보기**가 primary UX이며, panel을 닫은 뒤에는 `@codex-agent-view $show-agents`로 같은 bundled skill을 다시 호출한다. 별도 monitor 실행이나 task ID 등록이 필요 없다.
92
100
  - npm은 plugin bundle, 내부 hook sender/runtime과 static UI를 사용자 machine에 배포하는 최초 설치 경로다.
93
- - Live view는 사용자가 앱 안에서 **Show Agents**를 선택했을 때만 열린다. 외부 website나 telemetry dashboard가 아니다.
94
- - 공개 plugin API는 앱 시작 시 no-prompt sidebar/panel/Browser tab 생성을 제공하지 않는다. 최초 live view 열기에는 앱 안 skill 선택이 한 번 필요하고, 열린 tab은 같은 관찰 window에서 자동 갱신·재연결한다.
101
+ - Live view는 사용자가 앱 안에서 `$show-agents`를 명시 호출했을 때만 열린다. 외부 website나 telemetry dashboard가 아니다.
102
+ - 공개 plugin API는 앱 시작 시 no-prompt sidebar/panel/Browser tab 생성을 제공하지 않는다. 최초 live view 열기에는 앱 안 skill 선택이 한 번 필요하고, 열린 tab은 같은 설치의 viewer credential과 loopback origin이 유지되는 동안 일시 단절·monitor 재시작·upgrade 뒤에도 자동 갱신·재연결한다.
95
103
  - Universal Plugins Directory는 npm의 대체재가 아니다. 공개 directory의 in-app custom UI 경로는 public HTTPS MCP server와 domain verification이 필요해 local-only/no-external-server 원칙과 충돌한다. 현재는 별도의 listing/skills 제출 가능성만 검토하며, 심사·publish 전에는 Codex plugin 검색으로 설치할 수 있다고 안내하지 않는다.
96
104
 
97
105
  Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`, `stopped_without_start`, 빈 상태는 그대로 해석해야 한다. 빈 session 목록은 “이 monitor가 event를 관찰하지 못함”이며 “실행 중인 task가 없음”의 증거가 아니다.
@@ -100,12 +108,12 @@ Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`,
100
108
 
101
109
  이 절차는 위의 빠른 시작에서 설치와 활성화를 마친 뒤 **새 task**에서 수행한다. 별도 terminal이나 외부 browser는 사용하지 않는다.
102
110
 
103
- 1. 새 task의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택한다.
111
+ 1. Codex Agent View plugin 카드의 **지금 사용해보기**를 누른다. Starter `$show-agents`가 bundled **Show Agents** skill을 명시 호출한다.
104
112
  2. Skill은 trusted hook이 자동 준비한 healthy backend를 재사용하고, 아직 준비되지 않았다면 내부적으로 준비한 뒤 Codex 앱에서 live 화면 열기를 시도한다.
105
- 3. Panel은 관찰한 task와 subagent의 privacy-minimized hook 상태를 표시한다. Prompt, preview, tool input/output, full workspace path와 internal thread ID는 기본 표시하지 않는다.
113
+ 3. Panel은 실행 중인 부모 task와 subagent를 먼저 배치하고 사람이 읽을 수 있는 workspace/task/agent label과 상태 문구를 표시한다. Raw session/agent ID는 보조 진단 metadata이며 raw hook event name은 기본 화면을 주도하지 않는다. Prompt, preview, tool input/output과 full workspace path는 표시하지 않는다.
106
114
  4. 앱의 Browser capability 또는 permission을 사용할 수 없으면 private localhost URL을 노출하거나 외부 browser를 여는 대신 실패를 안내한다.
107
115
 
108
- 오른쪽 live 화면을 닫았다면 같은 `@` picker에서 bundled **Show Agents** skill 자체를 다시 직접 선택해 재오픈한다. 열린 tab은 같은 관찰 window에서 자동 갱신하고 일시 단절 뒤 재연결한다.
116
+ 오른쪽 live 화면을 닫았다면 Codex 앱 task에 `@codex-agent-view $show-agents`를 입력해 같은 bundled skill을 다시 호출한다. 열린 tab은 일시 단절·monitor 재시작·upgrade 뒤에도 자동 재연결한다. 재시작된 monitor는 과거 event를 재생하지 않고 새 in-memory 관찰 window를 표시한다.
109
117
 
110
118
  ### 요구사항과 검증 범위
111
119
 
@@ -168,7 +176,7 @@ node bin/codex-agent-view.mjs install
168
176
 
169
177
  ### Maintainer·고급 진단 전용 CLI
170
178
 
171
- 이 절은 package 개발자와 문제 보고를 위한 진단 참고 자료이며 일반 사용자 사용법이 아니다. 설치가 끝난 사용자는 Codex 앱의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택한다. 아래 명령과 localhost 주소를 정상 사용 순서에 넣거나 사용자에게 직접 관리하도록 요구하지 않는다.
179
+ 이 절은 package 개발자와 문제 보고를 위한 진단 참고 자료이며 일반 사용자 사용법이 아니다. 설치가 끝난 사용자는 plugin 카드의 **지금 사용해보기** 또는 Codex 앱 task의 `@codex-agent-view $show-agents`로 **Show Agents**를 호출한다. 아래 명령과 localhost 주소를 정상 사용 순서에 넣거나 사용자에게 직접 관리하도록 요구하지 않는다.
172
180
 
173
181
  Source checkout에서 local runtime을 별도로 검증해야 할 때만 다음처럼 실행할 수 있다.
174
182
 
@@ -198,24 +206,24 @@ Plugin enable/trust와 앱 재시작 뒤 생성되거나 재개되는 task는 tr
198
206
 
199
207
  ### npm 설치 명령 참고
200
208
 
201
- 아래 명령은 이 release와 일치하는 exact `0.4.1` 설치 명령이다. npm이 이 version을 찾지 못하면 registry publish가 완료됐는지 확인한 뒤 다시 시도한다.
209
+ 아래 명령은 아직 배포되지 않은 `0.4.3` release candidate의 exact 설치 명령이다. Registry publish가 확인된 뒤에만 실행하며, npm이 version을 찾지 못하면 candidate가 아직 공개되지 않은 것이다.
202
210
 
203
211
  ```bash
204
- npm install --global codex-agent-view@0.4.1
212
+ npm install --global codex-agent-view@0.4.3
205
213
  codex-agent-view install
206
214
  ```
207
215
 
208
- 이 두 명령 뒤에는 Codex 앱을 완전히 다시 열고 Plugins 화면에서 설치·활성화와 hook trust를 확인한 다음 새 task를 만든다. 첫 trusted hook이 backend 준비와 event 전달을 내부 처리하므로 사용자가 monitor CLI를 실행하지 않는다. 새 task의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택해 live 화면을 열며, 화면을 닫았으면 같은 skill을 다시 선택한다.
216
+ 이 두 명령 뒤에는 Codex 앱을 완전히 다시 열고 Plugins 화면에서 설치·활성화와 hook trust를 확인한 다음 새 task를 만든다. 첫 trusted hook이 backend 준비와 event 전달을 내부 처리하므로 사용자가 monitor CLI를 실행하지 않는다. Plugin 카드의 **지금 사용해보기**로 **Show Agents**를 호출하며, panel을 닫았으면 Codex 앱 task에 `@codex-agent-view $show-agents`를 입력해 다시 연다.
209
217
 
210
- `0.4.1`에서 지원하는 설치 경로는 위의 global package 설치와 명시적인 `codex-agent-view install` command 조합이다. 이후 일반 사용은 Codex 앱 안에서 진행한다.
218
+ `0.4.3`에서 계획한 설치 경로는 위의 global package 설치와 명시적인 `codex-agent-view install` command 조합이다. 이후 일반 사용은 Codex 앱 안에서 진행한다. 유효한 `0.4.2` 설치에서 upgrade하면 viewer credential이 없을 때에만 legacy runtime token을 새 read-only viewer credential로 migration하며 token과 private URL은 출력하지 않는다.
211
219
 
212
- `0.2.0`부터 `0.4.0`까지의 release evidence는 보존한다. `0.4.1` public release evidence는 해당 registry, artifact 또는 app 검증이 완료된 뒤에만 [docs/distribution.md](docs/distribution.md)에 추가한다.
220
+ `0.2.0`부터 public `0.4.2`까지의 release evidence는 보존한다. `0.4.3` candidate는 publish와 visual acceptance를 별도로 검증해 [docs/distribution.md](docs/distribution.md)에 기록하기 전까지 공개 완료로 취급하지 않는다.
213
221
 
214
222
  npm install 자체는 Codex 설정을 자동 변경하지 않는다. `install` command는 사용자가 명시적으로 실행하며 hook trust도 사용자 검토로 남긴다. npm publish와 Universal Plugins Directory 제출은 서로 별도 절차다. 자세한 배포 경계는 [docs/distribution.md](docs/distribution.md), directory 제출 상태는 [docs/plugin-submission.md](docs/plugin-submission.md)를 참고한다.
215
223
 
216
224
  ### Privacy와 opt-in diagnostic capture
217
225
 
218
- 정상 hook 경로는 `scripts/send-hook.mjs`다. 이 sender는 allowlisted metadata만 값으로 남기고 나머지는 type/key/length summary로 바꾼 뒤 loopback으로 보낸다. 전체 `cwd` 대신 control character를 제거하고 120자로 제한한 basename `workspace_label`만 파생한다. Runtime reducer는 lifecycle field와 이 label을 bounded memory에만 유지한다.
226
+ 정상 hook 경로는 `scripts/send-hook.mjs`다. 이 sender는 allowlisted metadata만 값으로 남기고 나머지는 type/key/length summary로 바꾼 뒤 loopback으로 보낸다. 전체 `cwd` 대신 control character를 제거하고 120자로 제한한 basename `workspace_label`만 파생한다. Runtime reducer는 lifecycle field와 이 label을 bounded memory에만 유지한다. 재연결용 private viewer credential에는 task나 hook event 상태가 들어가지 않는다.
219
227
 
220
228
  정상 monitor는 event JSONL을 쓰지 않는다. `scripts/capture-hook.mjs`는 Phase 0 검증용 별도 diagnostic script이며 누군가 명시적으로 실행하거나 hook에 연결할 때만 `events.jsonl`을 만든다.
221
229
 
@@ -231,7 +239,7 @@ npm install 자체는 Codex 설정을 자동 변경하지 않는다. `install` c
231
239
  codex-agent-view uninstall
232
240
  ```
233
241
 
234
- `uninstall`은 runtime file의 bearer token으로 loopback endpoint를 인증하고 Codex Agent View 소유의 healthy monitor인지 확인한 뒤 internal shutdown을 요청한다. 종료가 확인돼야 plugin 등록, marketplace 등록과 copied marketplace bundle을 제거하며 runtime directory에 남은 data는 기본적으로 보존한다. 인증된 소유 monitor를 안전하게 종료할 수 없거나 endpoint가 다른 service로 판별되면 plugin과 runtime files를 보존한 채 실패한다.
242
+ `uninstall`은 runtime/control token으로 loopback endpoint를 인증하고 Codex Agent View 소유의 healthy monitor인지 확인한 뒤 internal shutdown을 요청한다. 종료가 확인돼야 plugin 등록, marketplace 등록과 copied marketplace bundle을 제거한다. 정상 owned viewer credential은 기본 uninstall과 `--purge` 모두에서 폐기되며 나중에 다시 설치하면 다른 credential을 만든다. Runtime directory의 관련 없는 나머지 data는 기본적으로 보존한다. Viewer credential이 malformed, changed, symbolic 또는 그 밖의 unrecognized 상태라면 임의로 삭제하지 않고 manual review용으로 보존했다는 경고를 출력한다. 인증된 소유 monitor를 안전하게 종료할 수 없거나 endpoint가 다른 service로 판별되면 plugin과 runtime files를 보존한 채 실패한다.
235
243
 
236
244
  사용자가 configured runtime directory의 소유 data까지 제거하길 명시적으로 원할 때만 다음을 사용한다.
237
245
 
@@ -239,7 +247,7 @@ codex-agent-view uninstall
239
247
  codex-agent-view uninstall --purge
240
248
  ```
241
249
 
242
- `--purge`도 owned monitor를 같은 방식으로 먼저 종료하고, owned stale runtime file과 비어 있는 runtime directory만 추가 제거한다. 형식을 알 수 없는 runtime file과 관련 없는 loopback service는 삭제하거나 종료하지 않는다. Unrecognized file은 그대로 보존하며, unrelated endpoint가 확인되면 plugin과 runtime files를 모두 보존한 채 중단한다. Opt-in capture나 다른 file 때문에 directory가 비어 있지 않으면 directory 자체도 보존한다.
250
+ `--purge`도 owned monitor를 같은 방식으로 먼저 종료하고 정상 viewer credential을 폐기한 뒤, owned stale runtime file과 비어 있는 runtime directory만 추가 제거한다. 형식을 알 수 없는 runtime file·viewer credential과 관련 없는 loopback service는 삭제하거나 종료하지 않는다. Unrecognized file은 경고와 함께 그대로 보존하며, unrelated endpoint가 확인되면 plugin과 runtime files를 모두 보존한 채 중단한다. Opt-in capture나 다른 file 때문에 directory가 비어 있지 않으면 directory 자체도 보존한다.
243
251
 
244
252
  Source checkout을 직접 실행한 경우에만 같은 명령의 `node bin/codex-agent-view.mjs uninstall` 또는 `node bin/codex-agent-view.mjs uninstall --purge` 형식을 사용한다.
245
253
 
@@ -247,7 +255,7 @@ Source checkout을 직접 실행한 경우에만 같은 명령의 `node bin/code
247
255
 
248
256
  ### Maintainer troubleshooting
249
257
 
250
- 이 절의 CLI 확인은 명시적인 문제 조사용이다. 정상 사용자는 Codex 앱의 `@` picker에서 bundled **Show Agents** skill 자체를 직접 선택한다.
258
+ 이 절의 CLI 확인은 명시적인 문제 조사용이다. 정상 사용자는 plugin 카드의 **지금 사용해보기** 또는 Codex 앱 task의 `@codex-agent-view $show-agents`를 사용한다.
251
259
 
252
260
  #### `status`가 runtime file 또는 connection error를 출력함
253
261
 
package/README.md CHANGED
@@ -8,12 +8,12 @@ Codex Agent View is a read-only companion plugin that shows privacy-minimized ac
8
8
 
9
9
  ## Quick start: install once, then stay inside the Codex app
10
10
 
11
- This README documents the exact `codex-agent-view@0.4.1` release. Use the exact-version command below for the one-time terminal installation. If npm reports that this version is unavailable, verify that the `0.4.1` registry publication has completed before retrying.
11
+ This README documents the unpublished `codex-agent-view@0.4.3` release candidate. Use the exact-version command below for the one-time terminal installation only after `0.4.3` appears in the registry. Public npm `latest` is currently `0.4.2`.
12
12
 
13
13
  Universal Plugins Directory search installation is not available yet, so use a regular terminal for the **initial installation only**:
14
14
 
15
15
  ```bash
16
- npm install --global codex-agent-view@0.4.1
16
+ npm install --global codex-agent-view@0.4.3
17
17
  codex-agent-view install
18
18
  ```
19
19
 
@@ -25,20 +25,20 @@ After installation:
25
25
  2. In the Codex app's **Plugins** screen, confirm that `Codex Agent View` is installed and enabled.
26
26
  3. If a hook-review screen is shown, inspect `hooks/hooks.json` and the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command, then explicitly trust the current definition. Use interactive Codex CLI `/hooks` only as part of installation when the app version does not expose hook review.
27
27
  4. After enablement and hook review, create a **new task** in the Codex app. Events that occurred before installation are not replayed.
28
- 5. In the new task, open the `@` picker and directly select the bundled **Show Agents** skill.
29
- 6. If you close the live view, directly select **Show Agents** from the `@` picker again to reopen it.
28
+ 5. On the plugin card, select **Quick start**. Its `$show-agents` starter explicitly invokes the bundled **Show Agents** skill in a Codex app task.
29
+ 6. If you close the live view, enter `@codex-agent-view $show-agents` in a Codex app task to invoke the same bundled skill again.
30
30
 
31
- The plugin card's **Quick start** button only inserts the instruction `Open @ and select the bundled Show Agents skill.` It does not invoke the skill. Follow that instruction by opening the `@` picker and directly selecting the bundled **Show Agents** skill. `$show-agents` is not the supported Codex app GUI workflow.
31
+ The plugin card's **Quick start** action and the manual `@codex-agent-view $show-agents` composer entry are explicit in-app skill invocations. They do not require a terminal command, an external browser, or a localhost URL from the user.
32
32
 
33
33
  When the first trusted hook arrives, the plugin sender internally prepares the local backend and retries delivery of that same event. Users do not register task IDs or run `start`, `status`, or `doctor`. **Show Agents** reuses the healthy backend and attempts to open the live view in the Codex app without exposing a tokenized localhost URL or using an external browser. If the app does not provide the required Browser capability or permission, the skill reports that it could not open the view instead of exposing a private URL.
34
34
 
35
- The public Codex plugin API does not provide no-prompt app-start creation of a sidebar, panel, or Browser tab. Opening the live view therefore requires selecting **Show Agents** in a Codex app task. Once the right-side live tab is open, it refreshes every two seconds and reconnects after temporary disconnects while the same monitor observation window and token remain valid.
35
+ The public Codex plugin API does not provide no-prompt app-start creation of a sidebar, panel, or Browser tab. Opening the live view therefore requires the plugin card's explicit **Quick start** action or `@codex-agent-view $show-agents` in a Codex app task. Once the right-side live tab is open, it refreshes every two seconds and automatically reconnects after a temporary disconnect, monitor restart, or package upgrade when the backend returns on the same loopback origin. The live observation window still resets when the monitor process restarts; only the read-only viewer credential survives.
36
36
 
37
37
  In short: install once in a terminal; perform snapshot queries, status checks, live-view opening, and all routine use inside the Codex app.
38
38
 
39
39
  ## Status
40
40
 
41
- This repository and package are version `0.4.1`. They include an app-native snapshot skill that prioritizes the official Codex app's built-in thread tools, privacy-minimized hooks, a bounded in-memory reducer, a trusted-hook auto-prepared token-authenticated `127.0.0.1` live backend, and explicit install/remove plus maintainer-diagnostic CLI commands.
41
+ This repository and package are the unpublished `0.4.3` release candidate; registry verification on 2026-08-02 reports public npm `latest` as `0.4.2`. The candidate includes an app-native snapshot skill that prioritizes the official Codex app's built-in thread tools, privacy-minimized hooks, a bounded in-memory reducer, a trusted-hook auto-prepared token-authenticated `127.0.0.1` live backend, and explicit install/remove plus maintainer-diagnostic CLI commands.
42
42
 
43
43
  Plugin installation and lifecycle payloads were verified with Homebrew Codex CLI and the Codex executable embedded in the official app. However, a real-use attempt that installed and enabled `0.2.0` in an already-running official app process delivered zero events while two subagents ran. The monitor, registration, enablement, and installed bundle were healthy, while app logs showed no sender invocation. Evidence indicates that the same process retained a pre-install `hooks/list` snapshot; persisted exact-hook trust is not exposed through CLI JSON, so the precise skip boundary remains unconfirmed.
44
44
 
@@ -62,15 +62,23 @@ Public `0.4.0` evidence at the time of that release: npm `latest`/version, Apach
62
62
 
63
63
  Known `0.4.0` issue: manifest `defaultPrompt: ["Show Agents"]` created a plain plugin-level text starter. That text did not explicitly invoke the `show-agents` skill, whose implicit invocation was disabled, so treating the plugin card or its Quick start action as skill execution was incorrect. Version `0.4.1` replaces it with the instructional starter `Open @ and select the bundled Show Agents skill.` The starter remains guidance rather than invocation; the only canonical routine-use execution path is direct selection of the bundled **Show Agents** skill in a new task's `@` picker. Public registry and exact app E2E evidence for `0.4.1` are claimed only where separately verified and recorded.
64
64
 
65
+ Public `0.4.1`: npm `latest`/version, Apache-2.0 license, executable mapping, registry signature, 25 files, package size `53650 B`, unpacked size `193424 B`, shasum `ee2ae0b8b36016f5c57bade067027202b1508d1d`, and integrity `sha512-WC4f5MPmvpkXeKM+1BVAYqW4+hoaUrB4yQFoUYgc0pnjyY7hP1CdSR5NJ3QWmvJ6Ikmmb1d+58UL4hkKoyhm1Q==` were verified. The release tarball and registry tarball are byte-identical. npm metadata has no `gitHead` because the exact tarball was published, so source identity is not claimed through that field. The annotated `v0.4.1` tag points to commit `a1de67be5413fa38b8dd1b62f74353463f6e641e`; [GitHub Release v0.4.1](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.4.1), main CI run `30710490358`, and tag CI run `30710848474` are public and successful. This machine has matching CLI/plugin `0.4.1`, the plugin is installed/enabled, and all nine hooks are wired. The runtime was cleanly stopped while installation replaced it, so it currently reports `monitor_not_running`; persisted hook trust remains `unknown`. Because the Codex app process predates installation, direct **Show Agents** visual E2E remains unverified until a full app restart and a new task.
66
+
67
+ Public `0.4.2` changes the plugin starter to `$show-agents`, which explicitly invokes the bundled **Show Agents** skill from the plugin card; `@codex-agent-view $show-agents` is the manual in-app reopen path. Release commits `b4d923a` and `3d8f46d` were pushed, main CI run `30712375726` passed on Node.js 18/20/22, and npm publication was verified with `latest: 0.4.2`, Apache-2.0 licensing, the expected executable mapping, 25 files, registry signature, shasum `fac95689395baa26f4ad9ff0cbefd0017d2ebd8d`, and integrity `sha512-FRTPoYxjBuPC6Usb+ylSfZsZVJKlKcHnQPaAPljekg0maTPn9POsBkS+auOcHz5jspg0AXcP8R63PM0WfCn2LQ==`. The release and registry tarballs are byte-identical; annotated tag `v0.4.2` and [GitHub Release v0.4.2](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.4.2) are public. This machine's exact global install, plugin installed/enabled state, all nine hook declarations, installed artifact match, and official Codex in-app Browser visual E2E were also verified.
68
+
69
+ The unpublished `0.4.3` candidate preserves that app-only workflow and adds restart-safe live-view authentication. A user-only private viewer credential is separate from the runtime/control token and persists for the installed plugin's lifetime. The viewer credential can read `/api/state` but cannot ingest hook events or request shutdown; the runtime/control token rotates with the monitor process. Installing `0.4.3` over `0.4.2` seeds a missing viewer credential from the valid legacy runtime token without printing it, so an already-open Codex live tab can reconnect after the backend restarts on the same loopback origin. This credential continuity does not persist task state: restart still begins an empty bounded in-memory observation window.
70
+
65
71
  ## Boundaries
66
72
 
67
73
  Codex Agent View is a live companion, not a historical audit or session-replay product. Bounded in-memory state and reset-on-restart semantics are intentional: they keep privacy and failure boundaries small. SQLite or persistent history is not a missing requirement. Consider it only as a separate explicit opt-in feature if demonstrated user demand justifies retention, migration, deletion, and privacy costs.
68
74
 
69
75
  - The app-native current-task snapshot prioritizes explicit status and `subAgentActivity` from the official Codex app's built-in thread tools.
70
- - Hooks remain the source of truth for detailed lifecycle state in the trusted-hook auto-prepared local live backend. Its operational state exists only in bounded process memory; restart begins a new observation window.
76
+ - Hooks remain the source of truth for detailed lifecycle state in the trusted-hook auto-prepared local live backend. Its operational state exists only in bounded process memory; restart begins a new observation window. The separate private viewer credential is authentication metadata, not stored task history.
77
+ - The viewer credential is read-only and remains stable across monitor restarts and package upgrades during one installation. The runtime/control token remains separate and process-scoped.
71
78
  - After installation, hook trust, and an app restart, the first trusted hook automatically prepares the backend. This prepares a local process; it does not create app UI without a user action.
72
79
  - There is no external telemetry, remote server, account, required SQLite/persistent event store, or remote control.
73
80
  - Prompt text, transcript paths, full tool input/output, and assistant messages are not retained or displayed by the monitor.
81
+ - The default monitor sorts running parents and subagents first, uses human-readable labels and statuses as the primary presentation, and keeps raw IDs and event names out of the primary reading path.
74
82
  - The product cannot stop or restart tasks/subagents, send messages, or approve/deny permissions.
75
83
  - Missing, duplicated, or out-of-order events remain visible as empty, unknown, or degraded state instead of being guessed away.
76
84
 
@@ -78,22 +86,22 @@ A separately launched Codex `0.146` App Server `thread/list` fallback was also t
78
86
 
79
87
  ## The roles of npm, the Codex app live view, and the Plugins Directory
80
88
 
81
- - Directly selecting the bundled **Show Agents** skill from the official Codex app's `@` picker is the canonical UX; it does not require starting a monitor or registering task IDs.
89
+ - The plugin card's **Quick start** action is the primary UX; `@codex-agent-view $show-agents` manually invokes the same bundled skill again after a panel is closed. Neither path requires starting a monitor or registering task IDs.
82
90
  - npm is the initial installation path that distributes the plugin bundle, its internal hook sender/runtime, and static UI to the user's machine.
83
- - The live view opens in the Codex app only after the user selects **Show Agents**; it is not an external website or telemetry dashboard.
84
- - The public plugin API cannot create a sidebar, panel, or Browser tab without a prompt at app startup. The first live view needs one in-app skill selection; an already-open tab refreshes and reconnects within the same observation window.
91
+ - The live view opens in the Codex app only after an explicit `$show-agents` skill invocation; it is not an external website or telemetry dashboard.
92
+ - The public plugin API cannot create a sidebar, panel, or Browser tab without a prompt at app startup. The first live view needs one in-app skill selection; an already-open tab refreshes and reconnects across temporary disconnects, monitor restarts, and upgrades while the same installation-owned viewer credential and loopback origin remain available.
85
93
  - The Universal Plugins Directory does not replace npm. A public in-app custom UI path requires a public HTTPS MCP server and domain verification, which conflicts with this project's local-only, no-external-server boundary. Only a separate listing/skills submission remains under consideration; do not expect Directory search installation until review and publication actually finish.
86
94
 
87
95
  ## Use in the official Codex app — recommended
88
96
 
89
97
  Use this flow in a **new task** after completing installation and enablement in the quick start. It requires neither another terminal nor an external browser.
90
98
 
91
- 1. Open the task's `@` picker and directly select the bundled **Show Agents** skill.
99
+ 1. Select **Quick start** on the Codex Agent View plugin card. Its `$show-agents` starter explicitly invokes the bundled **Show Agents** skill.
92
100
  2. The skill reuses the backend prepared by trusted hooks, or prepares it internally when still absent, then attempts to open the live view in the Codex app.
93
- 3. The panel displays privacy-minimized hook state for observed tasks and subagents. Prompts, previews, tool input/output, full workspace paths, and internal thread IDs remain hidden by default.
101
+ 3. The panel puts running parents and subagents first and uses human-readable workspace/task/agent labels and status text. Raw session/agent IDs are secondary diagnostic metadata, raw hook event names do not lead the default display, and prompts, previews, tool input/output, and full workspace paths remain hidden.
94
102
  4. If the app's Browser capability or permission is unavailable, the skill reports the failure without exposing a private localhost URL or opening an external browser.
95
103
 
96
- If you close the right-side live view, directly select the bundled **Show Agents** skill from the same `@` picker again. An open tab refreshes and reconnects automatically within the same observation window.
104
+ If you close the right-side live view, enter `@codex-agent-view $show-agents` in a Codex app task to invoke the same bundled skill again. An open tab refreshes and reconnects automatically after temporary disconnects, monitor restarts, and upgrades. A restarted monitor presents a new in-memory observation window rather than replaying earlier activity.
97
105
 
98
106
  ## Requirements and tested versions
99
107
 
@@ -127,7 +135,7 @@ Review the installed plugin and `hooks/hooks.json`, inspect the `node "${PLUGIN_
127
135
 
128
136
  ## Maintainer and advanced diagnostics CLI
129
137
 
130
- This section is reference material for package maintainers and explicit troubleshooting. It is not the normal user workflow. After installation, users directly select the bundled **Show Agents** skill from the app's `@` picker; do not make them manage these commands or localhost URLs.
138
+ This section is reference material for package maintainers and explicit troubleshooting. It is not the normal user workflow. After installation, users invoke **Show Agents** with the plugin card's **Quick start** action or `@codex-agent-view $show-agents` inside a Codex app task; do not make them manage these commands or localhost URLs.
131
139
 
132
140
  Only when validating the local runtime from a source checkout, a maintainer can start it without opening an operating-system browser:
133
141
 
@@ -150,18 +158,18 @@ After plugin enablement/trust and an app restart, the first trusted hook interna
150
158
 
151
159
  ## Install from npm
152
160
 
153
- The commands below target this release's exact package version, `0.4.1`. If npm reports that the version is unavailable, verify that registry publication has completed before retrying.
161
+ The commands below target the unpublished `0.4.3` release candidate's exact package version. Run them only after registry publication is confirmed; an unavailable version means the candidate has not been published yet.
154
162
 
155
163
  ```bash
156
- npm install --global codex-agent-view@0.4.1
164
+ npm install --global codex-agent-view@0.4.3
157
165
  codex-agent-view install
158
166
  ```
159
167
 
160
- After these two commands, fully reopen the Codex app, verify installation, enablement, and hook trust, then create a new task. The first trusted hook prepares the backend and delivers its event internally, so users do not run monitor CLI commands. In that task's `@` picker, directly select the bundled **Show Agents** skill to open the live view; select the same skill whenever a closed view needs to be reopened.
168
+ After these two commands, fully reopen the Codex app, verify installation, enablement, and hook trust, then create a new task. The first trusted hook prepares the backend and delivers its event internally, so users do not run monitor CLI commands. Use the plugin card's **Quick start** action to invoke **Show Agents**; after closing the panel, enter `@codex-agent-view $show-agents` in a Codex app task to reopen it.
161
169
 
162
- The supported `0.4.1` installation path is the global package install followed by the explicit `codex-agent-view install` command above. Routine use remains inside the Codex app afterward.
170
+ The planned `0.4.3` installation path is the global package install followed by the explicit `codex-agent-view install` command above. Routine use remains inside the Codex app afterward. When upgrading a valid `0.4.2` installation, `install` migrates its legacy runtime token into the new read-only viewer credential only when that credential does not already exist; neither token nor the private URL is printed.
163
171
 
164
- The `0.2.0` through `0.4.0` release evidence is preserved. Public release evidence for `0.4.1` is added to [Distribution](docs/distribution.md) only after the corresponding registry, artifact, or app verification is complete.
172
+ The `0.2.0` through public `0.4.2` release evidence is preserved. The `0.4.3` candidate must not be treated as published or visually accepted until those checks are separately recorded in [Distribution](docs/distribution.md).
165
173
 
166
174
  npm installation does not modify Codex settings automatically. The explicit `install` command performs local plugin registration and leaves hook trust to the user. npm publication and Universal Plugins Directory submission are separate. See [Distribution](docs/distribution.md) and [Plugin submission](docs/plugin-submission.md).
167
175
 
@@ -177,7 +185,7 @@ If events are still absent, report the Codex app/CLI version, plugin version, ap
177
185
 
178
186
  ## Privacy
179
187
 
180
- The normal hook path uses `scripts/send-hook.mjs`. It derives only a sanitized, 120-character-bounded workspace basename as `workspace_label`; the full `cwd` is not sent or stored as content. The reducer keeps this label and narrower lifecycle state only in bounded memory. The normal monitor does not write an event JSONL history.
188
+ The normal hook path uses `scripts/send-hook.mjs`. It derives only a sanitized, 120-character-bounded workspace basename as `workspace_label`; the full `cwd` is not sent or stored as content. The reducer keeps this label and narrower lifecycle state only in bounded memory. The normal monitor does not write an event JSONL history. The private viewer credential stored for reconnect continuity contains no task or hook-event state.
181
189
 
182
190
  `scripts/capture-hook.mjs` is a separate, explicitly invoked Phase 0 diagnostic tool. Setting `CODEX_AGENT_VIEW_CAPTURE_FULL=1` for that script can write raw prompts, tool data, credentials, and other secrets. Normal install/start and the bundled skill never enable it automatically. Do not commit or publicly attach captures or runtime tokens.
183
191
 
@@ -191,7 +199,7 @@ Uninstall is an explicit terminal lifecycle action, like initial installation. R
191
199
  codex-agent-view uninstall
192
200
  ```
193
201
 
194
- `uninstall` authenticates to the loopback endpoint with the runtime file's bearer token, verifies that it is a healthy owned Codex Agent View monitor, and requests internal shutdown. Only after shutdown is confirmed does it remove plugin/marketplace registration and the copied bundle; remaining runtime-directory data is preserved by default. If the owned monitor cannot be stopped safely or the endpoint is identified as another service, plugin and runtime files are preserved and the command fails.
202
+ `uninstall` authenticates to the loopback endpoint with the runtime/control token, verifies that it is a healthy owned Codex Agent View monitor, and requests internal shutdown. Only after shutdown is confirmed does it remove plugin/marketplace registration and the copied bundle. A valid owned viewer credential is revoked during both normal uninstall and `--purge`; reinstalling later creates a different credential. Remaining unrelated runtime-directory data is preserved by default. If the viewer credential is malformed, changed, symbolic, or otherwise unrecognized, it is preserved for manual review and the command prints a warning rather than deleting uncertain data. If the owned monitor cannot be stopped safely or the endpoint is identified as another service, plugin and runtime files are preserved and the command fails.
195
203
 
196
204
  Use the following only after explicitly deciding to remove owned data from the configured runtime directory:
197
205
 
@@ -199,7 +207,7 @@ Use the following only after explicitly deciding to remove owned data from the c
199
207
  codex-agent-view uninstall --purge
200
208
  ```
201
209
 
202
- `--purge` performs the same authenticated shutdown first, then additionally removes only an owned stale runtime file and an empty runtime directory. It does not delete or stop an unrecognized runtime file or an unrelated loopback service. An unrecognized file is preserved; an unrelated endpoint aborts removal while preserving plugin and runtime files. A non-empty directory containing opt-in captures or other files is also preserved.
210
+ `--purge` performs the same authenticated shutdown and valid viewer-credential revocation first, then additionally removes only an owned stale runtime file and an empty runtime directory. It does not delete or stop an unrecognized runtime file, an unrecognized viewer credential, or an unrelated loopback service. Unrecognized files are preserved with a warning; an unrelated endpoint aborts removal while preserving plugin and runtime files. A non-empty directory containing opt-in captures or other files is also preserved.
203
211
 
204
212
  For a source checkout only, use the equivalent `node bin/codex-agent-view.mjs uninstall` or `node bin/codex-agent-view.mjs uninstall --purge` form. Opt-in captures outside that directory require separate, exact cleanup.
205
213
 
package/bin/codex-agent-view.mjs CHANGED
@@ -17,10 +17,14 @@ import { fileURLToPath } from "node:url";
17
17
  import { startMonitorServer } from "../src/runtime/server.mjs";
18
18
  import {
19
19
  DEFAULT_PORT,
20
+ ensureViewerToken,
20
21
  readRuntimeInfo,
22
+ readViewerToken,
21
23
  removeRuntimeInfo,
24
+ removeViewerToken,
22
25
  runtimeDirectory,
23
26
  runtimeFile,
27
+ viewerCredentialFile,
24
28
  } from "../src/runtime/config.mjs";
25
29
 
26
30
  const PACKAGE_ROOT = resolve(fileURLToPath(new URL("../", import.meta.url)));
@@ -167,7 +171,11 @@ async function start(args) {
167
171
  throw new Error("a Codex Agent View monitor is already running; stop it before starting another");
168
172
  }
169
173
 
170
- const monitor = await startMonitorServer({ port: options.port });
174
+ const viewerToken = await ensureViewerToken();
175
+ const monitor = await startMonitorServer({
176
+ port: options.port,
177
+ viewerToken,
178
+ });
171
179
  let stopping = false;
172
180
  const stop = async () => {
173
181
  if (stopping) return;
@@ -442,6 +450,39 @@ async function inspectRuntime() {
442
450
  }
443
451
  }
444
452
 
453
+ async function inspectViewerCredential() {
454
+ const path = viewerCredentialFile();
455
+ const stats = await pathExists(path);
456
+ if (!stats) {
457
+ return { kind: "absent", path };
458
+ }
459
+ if (!stats.isFile() || stats.isSymbolicLink()) {
460
+ return { kind: "unknown", path };
461
+ }
462
+ try {
463
+ return { kind: "valid", path, token: await readViewerToken() };
464
+ } catch {
465
+ return { kind: "unknown", path };
466
+ }
467
+ }
468
+
469
+ async function revokeViewerCredential(preflight) {
470
+ if (preflight.kind === "absent") {
471
+ return { preserved: false, removed: false };
472
+ }
473
+ if (preflight.kind === "unknown") {
474
+ return { preserved: true, removed: false };
475
+ }
476
+ if (await removeViewerToken(preflight.token)) {
477
+ return { preserved: false, removed: true };
478
+ }
479
+ const current = await inspectViewerCredential();
480
+ return {
481
+ preserved: current.kind !== "absent",
482
+ removed: current.kind === "absent",
483
+ };
484
+ }
485
+
445
486
  async function runtimeEndpointState(runtime) {
446
487
  try {
447
488
  const response = await fetch(`http://${runtime.host}:${runtime.port}/api/state`, {
@@ -620,6 +661,15 @@ async function install() {
620
661
  `marketplace ${MARKETPLACE_NAME} already points to ${existing.root}; remove it explicitly before installing this npm bundle`,
621
662
  );
622
663
  }
664
+ const bundle = await inspectPluginBundle(destination);
665
+ if (bundle.kind === "unmanaged") {
666
+ throw unmanagedBundleError(destination);
667
+ }
668
+ const runtime = await inspectRuntime();
669
+ const seedToken = runtime.kind === "valid"
670
+ ? runtime.info.viewer_token || runtime.info.token
671
+ : undefined;
672
+ await ensureViewerToken(process.env, { seedToken });
623
673
  await copyPluginBundle(destination);
624
674
  if (!existing) {
625
675
  await run("codex", ["plugin", "marketplace", "add", destination, "--json"]);
@@ -739,6 +789,7 @@ async function uninstall(args) {
739
789
  }
740
790
 
741
791
  const runtimePreflight = await inspectRuntime();
792
+ const viewerPreflight = await inspectViewerCredential();
742
793
  const stoppedMonitor = await stopRunningRuntime(runtimePreflight);
743
794
 
744
795
  await run("codex", ["plugin", "remove", PLUGIN_ID, "--json"], { allowFailure: true });
@@ -746,6 +797,7 @@ async function uninstall(args) {
746
797
  allowFailure: true,
747
798
  });
748
799
  await removeManagedPluginBundle(bundle);
800
+ const viewerCredential = await revokeViewerCredential(viewerPreflight);
749
801
  if (purge) {
750
802
  const preservedRuntimeFile = await purgeStaleRuntime(runtimePreflight);
751
803
  const removedRoot = await removeRuntimeRootIfEmpty(root);
@@ -761,12 +813,22 @@ async function uninstall(args) {
761
813
  `The unrecognized runtime file at ${runtimeFile()} was preserved.\n`,
762
814
  );
763
815
  }
816
+ if (viewerCredential.preserved) {
817
+ process.stdout.write(
818
+ "The unrecognized or changed viewer credential was preserved for manual review.\n",
819
+ );
820
+ }
764
821
  } else {
765
822
  process.stdout.write(
766
823
  stoppedMonitor
767
824
  ? "Stopped the owned monitor and removed the plugin and marketplace bundle.\n"
768
825
  : "Removed plugin and marketplace bundle. Runtime data was preserved.\n",
769
826
  );
827
+ if (viewerCredential.preserved) {
828
+ process.stdout.write(
829
+ "The unrecognized or changed viewer credential was preserved for manual review.\n",
830
+ );
831
+ }
770
832
  }
771
833
  }
772
834
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-agent-view",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "Read-only Codex app task view with a trusted-hook auto-prepared local live backend.",
5
5
  "type": "module",
6
6
  "main": "./src/core/index.mjs",