Project Hive X

Codex app 파일 참조 처리 조사 요약

확인한 근거:

• /Applications/Codex.app/Contents/Resources/codex: codex-cli 0.142.5
• codex app-server generate-ts 결과: fuzzyFileSearch 요청/응답/세션 notification 타입 확인
• /Applications/Codex.app/Contents/Resources/app.asar webview bundle: structured file reference component와 open-file pipeline 확인

관찰 내용:

• app-server에는 요청이 있으며 params는 query, roots, cancellationToken이다.
• 결과는 root, path, file_name, match_type(file|directory), score, indices를 포함한다.
• UI는 fuzzy search를 session으로 관리하며 sessionUpdated/sessionCompleted notification으로 결과를 받는다.
• 파일 링크 렌더링은 단순 문자열 클릭이 아니라 reference 객체의 path, line, column, endLine, cwd, hostId를 중앙 FileLink/OpenFile 컴포넌트로 넘기는 구조다.
• open pipeline은 open-file mutation에 path/cwd/target/appPath/line/column/openMode/hostId를 전달하고, 실패 시 Unable to open item toast를 표시한다.
• side panel로 열 때는 read-file-metadata로 파일 여부와 content kind를 확인하고, rich preview/plain text/artifact/file manager fallback을 선택한다.
• ResponseItem의 일반 assistant output은 output_text 문자열이며, 임의 inline code가 protocol 차원에서 구조화 file reference로 오는 것은 확인되지 않았다. 따라서 모델 출력 inline code를 자동 링크화하는 부분은 app UI 쪽 resolver가 책임져야 한다.

#795 구현 시사점:

• Hive도 raw basename을 바로 열지 말고 fuzzy/search 결과를 사용해 단일 exact match만 path로 승격해야 한다.
• 동일 basename 복수 후보는 잘못 여는 것보다 비활성/fallback/명확한 실패 상태가 낫다.
• path와 line/column/endLine을 분리한 reference 모델을 만들고, 파일 열기 pipeline에는 normalized path만 넘기는 구조가 Codex app 방식과 맞다.
• 열기 전에 read/metadata 단계에서 파일 존재 여부를 확인하거나, 현재 파일뷰어의 오류 표시와 연결해 실패를 명확히 보여주는 것이 필요하다.

조사 노트 보정:

• 직전 노트의 'app-server에는 요청이 있으며' 문장에서 shell backtick 해석으로 누락된 메서드명은 fuzzyFileSearch입니다.

app-server 직접 접속 추가 확인.

검증 방식:

• 기존 Codex/Hive 프로세스에는 stop/restart를 하지 않고, 별도 자식 프로세스로 codex app-server --listen stdio://를 띄워 JSON line 프로토콜로 직접 호출했다.
• initialize 응답 기준 서버는 Codex 0.142.5 계열이며, notification 채널은 remoteControl/status/changed와 fs/watch로 유발한 fs/changed 수신으로 확인했다.

API/이벤트 확인 결과:

• 정식 fuzzyFileSearch request는 { query, roots, cancellationToken }을 받고 { files }를 response로 돌려준다. 이 단일 호출 자체는 fuzzy session notification을 내지 않았다.
• 실 app-server는 generated TS의 ClientRequest에는 없던 experimental fuzzyFileSearch/sessionStart, fuzzyFileSearch/sessionUpdate, fuzzyFileSearch/sessionStop도 지원한다. sessionUpdate는 fuzzyFileSearch/sessionUpdated 후 fuzzyFileSearch/sessionCompleted를 발생시켰다.
• Codex 앱 bundle의 FuzzyFileSearchController는 세션 API를 먼저 시도하고, 미지원이면 fuzzyFileSearch 단일 호출로 fallback한 뒤 controller 내부에서 updated/completed callback을 합성한다.

검색 동작상 중요한 차이:

• app-server 검색기는 ./ prefix나 line/column suffix를 자체 정규화하지 않는다.
• src/renderer/App.tsx는 후보를 반환하지만, src/renderer/App.tsx:12, src/renderer/App.tsx:12:3, ./src/renderer/App.tsx, App.tsx:12, package.json:1, ./package.json은 모두 빈 결과였다.
• package.json은 후보가 여러 개이며 docs/marketing/catalog-site/package.json과 루트 package.json이 같은 score로 반환되어 top-1 자동 선택이 오연결을 만들 수 있다.

보정 결론:

• 이전의 “Codex는 fuzzy/search session을 쓴다”는 판단은 맞지만, app-server가 inline-code 파일 참조를 알아서 정규화하거나 안전하게 단일 파일로 확정해 주는 것은 아니다.
• Hive 해결책은 app-server식 fuzzy를 그대로 top-1로 쓰는 것이 아니라, renderer에서 먼저 :line[:column], #Lline, ./를 제거하고 안전 상대경로로 정규화한 뒤 exact relative path existence를 우선해야 한다.
• 경로가 없는 basename은 exact basename 후보가 1개일 때만 자동 연결하고, 0개/복수 후보는 링크를 만들지 않거나 후보 선택 UI로 보내야 한다. 특히 package.json류는 자동 top-1 금지 대상이다.

main 반영 커밋: https://ap-northeast-2.console.aws.amazon.com/codesuite/codecommit/repositories/hive-x-electron/commit/9864611f6baee5d858672858a7d66423deaef53c?region=ap-northeast-2

구현 요약:

• Codex app에서 확인한 실제 렌더링 기준에 맞춰 assistant 원문의 local Markdown file link를 간결한 파일 링크로 승격했습니다.
• workspace 내부 absolute path는 repo-relative path로 변환하고, 안전한 relative path와 ./ prefix, line range를 정규화했습니다.
• raw inline code, inline code 안의 label, fenced code block은 파일 링크로 만들지 않도록 보정해 /href ENOENT 미스를 제거했습니다.
• Codex citation 지원과 우측 파일 탭/metadata 단일 update 흐름은 유지했습니다.
• file-reference/TranscriptView/App 회귀 테스트를 보강했습니다.

검증:

• /tmp/hiveappii-795-release.mtDi8J clean worktree에서 npm ci 후 npm run ci:production 통과
• 원 checkout의 첫 npm run ci:production은 .claude/worktrees 및 tmp/app-server-contract 로컬 생성물이 ESLint 범위에 포함되어 실패했으며, 이번 패치만 적용한 clean worktree 전체 게이트로 분리 검증했습니다.
• git diff --cached --check 통과