From 13f754012e1f9085cf37717b37742f88382b3499 Mon Sep 17 00:00:00 2001 From: Son Seong Jun <166786347+SonAIengine@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:20:36 +0900 Subject: [PATCH 1/2] =?UTF-8?q?=EC=B5=9C=EC=B4=88=20=EC=84=A4=EC=B9=98?= =?UTF-8?q?=EC=99=80=20=EB=AA=A8=EB=8D=B8=20=EC=84=A4=EC=A0=95=20=EB=B3=B5?= =?UTF-8?q?=EA=B5=AC=EB=A5=BC=20=EA=B0=9C=EC=84=A0=ED=95=98=EA=B3=A0=20rc.?= =?UTF-8?q?7=20=EB=B0=B0=ED=8F=AC=20=EC=A4=80=EB=B9=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/ci.yml | 15 ++ .gitignore | 1 + Cargo.lock | 22 +-- Cargo.toml | 2 +- MEMORY.md | 9 +- README.md | 45 ++--- THIRD_PARTY_LICENSES.txt | 22 +-- crates/xgen-cli/src/main.rs | 157 +++++++++++++++- .../xgen-cli/tests/environment_onboarding.rs | 2 + crates/xgen-cli/tests/model_profiles.rs | 4 + .../0088-first-use-preview-distribution.md | 71 +++++++ docs/development/model-onboarding.md | 27 ++- docs/development/npm-distribution.md | 7 + docs/development/releasing.md | 2 +- docs/getting-started.md | 46 +++-- npm/package-lock.json | 20 +- npm/package.json | 5 +- npm/packages/cli/README.md | 22 ++- npm/packages/cli/package.json | 12 +- npm/scripts/publish.mjs | 41 ++++- npm/scripts/smoke.mjs | 9 +- npm/scripts/verify-release.mjs | 3 +- npm/tests/publish-contract.test.mjs | 29 +++ scripts/check-npm-distribution-workflow.sh | 6 +- scripts/check-rc3-public-docs.sh | 4 +- scripts/smoke-first-use.py | 174 ++++++++++++++++++ 26 files changed, 648 insertions(+), 109 deletions(-) create mode 100644 docs/adr/0088-first-use-preview-distribution.md create mode 100644 scripts/smoke-first-use.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6c705df..d90ec28 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,10 +65,25 @@ jobs: sudo apt-get update sudo apt-get install --yes tmux fi + python3 scripts/smoke-first-use.py python3 scripts/smoke-inline-tui.py python3 scripts/smoke-inline-tui.py --rapid-resize python3 scripts/smoke-inline-tui.py --results --rapid-resize + - name: Install pinned Node.js + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6 + with: + node-version: 24.20.0 + package-manager-cache: false + + - name: Check npm distribution contract + shell: bash + run: | + set -euo pipefail + npm ci --ignore-scripts --prefix npm + npm run check --prefix npm + npm test --prefix npm + - name: Test Python scripts without API calls run: python3 -m unittest discover -s scripts/tests diff --git a/.gitignore b/.gitignore index dbc0b22..ef023b2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target/ +/npm/node_modules/ .DS_Store Thumbs.db .idea/ diff --git a/Cargo.lock b/Cargo.lock index d17e3d6..2782667 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2941,7 +2941,7 @@ checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" [[package]] name = "xgen-adapter-filesystem" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "cap-fs-ext", "cap-std", @@ -2960,7 +2960,7 @@ dependencies = [ [[package]] name = "xgen-adapter-process" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "cap-fs-ext", "cap-std", @@ -2983,7 +2983,7 @@ dependencies = [ [[package]] name = "xgen-adapter-reference" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "jsonschema", "serde", @@ -3001,7 +3001,7 @@ dependencies = [ [[package]] name = "xgen-cli" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "cap-fs-ext", "cap-std", @@ -3038,7 +3038,7 @@ dependencies = [ [[package]] name = "xgen-domain" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "serde", "serde_json", @@ -3046,7 +3046,7 @@ dependencies = [ [[package]] name = "xgen-local-store" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "libc", "rusqlite", @@ -3064,7 +3064,7 @@ dependencies = [ [[package]] name = "xgen-policy" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "serde_json", "thiserror 2.0.20", @@ -3073,7 +3073,7 @@ dependencies = [ [[package]] name = "xgen-protocol" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "jsonschema", "serde", @@ -3086,7 +3086,7 @@ dependencies = [ [[package]] name = "xgen-provider-openai" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "jsonschema", "serde", @@ -3105,7 +3105,7 @@ dependencies = [ [[package]] name = "xgen-runtime" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "jsonschema", "serde", @@ -3124,7 +3124,7 @@ dependencies = [ [[package]] name = "xgen-workgraph" -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" dependencies = [ "proptest", "serde", diff --git a/Cargo.toml b/Cargo.toml index a22d963..18a3d02 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,7 +15,7 @@ members = [ resolver = "3" [workspace.package] -version = "0.1.0-rc.6" +version = "0.1.0-rc.7" edition = "2024" rust-version = "1.98" license = "Apache-2.0" diff --git a/MEMORY.md b/MEMORY.md index a7e7b74..9837a7a 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -1,6 +1,6 @@ # xgen CLI와 연계 도구 공동 개발 메모 -갱신: 2026-11-03 (KST) +갱신: 2026-11-19 (KST) ## 사용자가 정한 방향 @@ -14,6 +14,13 @@ ## 책임과 개발 범위 +2026-11-19 구현·로컬 검증: [최초 사용과 기본 preview 설치](docs/adr/0088-first-use-preview-distribution.md). +실행 파일 없는 bootstrap을 기본 설치로 받는 문제를 고쳐 첫 stable 전에는 검증한 launcher preview를 +`latest`로 제공한다. Provider/model 오입력 재선택과 정적 오류 복구 안내, 현재 OpenAI preset 안내를 +추가했다. Rust800개·npm19개·격리한 CLI의 3개 edit/test/approval-resume layout과 TUI smoke를 통과했다. +rc.7 게시·공개 registry 기본 설치는 검증 예정이며 실제 모델 품질 평가는 인증 부재로 미실행이다. +소유자는 xgen CLI·npm 배포 경로다. 도구 검색·browser-use·SEV 알고리즘은 이번 변경 대상이 아니다. + 2026-11-19 구현·로컬 검증 완료: [Run별 capability 범위](docs/development/capability-scope.md), [PR #144](https://github.com/PlateerLab/xgen-cli/pull/144). `run --capability ID`는 선택한 정의와 instance만 planner/admission에 등록하고 manifest와 실행 profile에 결속한다. 기본 전체 catalog·기존 승인·Receipt를 유지하며 resume은 저장한 범위를 diff --git a/README.md b/README.md index 28f4a48..556da0f 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,20 @@ # XGEN CLI -Local-first general-purpose agent CLI and harness. +터미널에서 프로젝트를 읽고 수정하고 테스트하는 로컬 에이전트야. 하단 입력창, 실행 중 상태 표시, +승인, 실행 기록과 중단한 작업 재개를 제공해. 로컬 또는 원격 OpenAI-compatible 모델에 연결해서 써. -> 현재 상태: 프로토콜 v0.1 검증, dependency DAG와 Receipt-gated 재개 frontier를 갖춘 model-free WorkGraph, embedded SQLite schema 8 store, effect 실행·복구 조정기, 결정론적 Capability Registry·Router, I/O 없는 Permission Broker, secret-free invocation material 복구, Direct Executor와 Core-owned Execution Receipt 검증 경계, 장기 Run용 VerifiedRunIndex를 실행할 수 있습니다. Provider-neutral bounded AgentLoop는 비신뢰 `PlanProposal`을 검증해 다중 Step DAG와 reconstructable input sidecar를 원자 commit하고 재시작 뒤 한 frontier action씩 이어갑니다. Model call은 provider 호출 전에 보수적인 possible-send slot을 journal에 예약하며 accepted/rejected/Unknown을 재시작 뒤 복원하고, 불확정 호출을 자동 재시도하지 않습니다. 별도 `xgen-provider-openai` leaf adapter는 OpenAI-compatible Chat Completions의 단일 요청과 strict structured proposal을 이 lifecycle에 연결합니다. 내부 WorkGraph는 planned `ReadOnly`/`Idempotent`/`NonIdempotent`, Core Receipt v2의 bounded Artifact commitment와 event-anchored typed `ToolOutputRecord`를 지원하며, generation-checked `PlanningContext v3`는 Step의 plan journal 순서와 passed Receipt에 결합된 exact ToolOutput의 관찰 순서를 보존해 다음 model turn에 전달합니다. NonIdempotent durable output은 결과만 보존하고 Started 뒤 불확정 effect의 no-replay 의미는 유지합니다. Public `xgen run/resume`은 기존 exact `--allow-file` mode를 보존하면서, 명시적 `--allow-dir` mode에서 네 read Capability와 `write-atomic`·`apply-patch`로 workspace를 탐색·수정합니다. Host가 등록한 executable은 별도 승인 뒤 shell 없이 bounded cwd·argv·환경·timeout·출력 제한으로 실행하며 결과를 durable하게 보존하고 불확정 실행을 자동 반복하지 않습니다. Dynamic path/query/write/process material은 Run 전용 embedded `materials.sqlite3`에 digest-bound recipe로 저장되어 approval pause 뒤 다른 process에서도 복원됩니다. 모델 프로필은 일반 설정과 OS 보안 credential 저장소를 분리하고 catalog와 실제 strict-JSON inference를 모두 검증합니다. Bare `xgen`는 이 경계 위에서 Thinking 표시와 검증된 최종 응답을 제공하고 model/read/write/execute를 각각 묻는 가벼운 REPL을 시작합니다. 로컬 JSON OpenAPI 명세로 연결한 제한된 HTTP GET·호스트 지정 POST 조회는 지원합니다. 지원 범위는 [HTTP 조회 문서](docs/development/http-read-tools.md)를 따르며, HTTP 쓰기·범용 MCP 클라이언트·XGEN compatibility adapter는 후속 범위입니다. +**Developer Preview** 단계야. 모델에 따라 작업이 반복되거나 일부 수정만 끝낼 수 있어. +실행 결과와 diff를 확인하고 쓰는 걸 권장해. HTTP 조회는 지원하며 HTTP 쓰기·범용 MCP 클라이언트는 후속 범위야. ## 설치와 첫 모델 연결 -`v0.1.0-rc.6` release artifact가 게시되면 Linux x86-64/ARM64, macOS Intel/Apple Silicon, Windows -x86-64용 동일 native binary를 GitHub checksum installer와 npm 두 경로로 제공합니다. Native installer는 -Rust, Node.js, Python, SQLite 실행 파일이나 XGEN state용 별도 daemon을 요구하지 않습니다. npm 경로만 -얇은 launcher를 위해 Node.js 22.14 이상이 필요하며 install script, GitHub 추가 download와 native -compile은 수행하지 않습니다. 사용할 model endpoint는 로컬 또는 원격에 별도로 실행 중이어야 합니다. -후보 version PR의 merge만으로 artifact가 생기지는 않으며 GitHub/npm에 해당 version이 게시된 뒤 설치 -명령을 사용해야 합니다. - -Node.js가 이미 있다면 exact RC를 npm으로 설치할 수 있습니다. `--omit=optional`은 native package를 -제거하므로 사용하지 않습니다. +Node.js 22.14 이상이면 npm으로 설치해. 최초 stable 게시 전까지 기본 설치는 검증된 최신 preview를 +가리켜. 이후 기본 설치는 stable을 따르고, preview는 `@next`로 선택할 수 있어. +Linux x86-64/ARM64, macOS Intel/Apple Silicon, Windows x86-64를 지원해. +`--omit=optional`은 실행 파일을 빼므로 사용하지 마. ```bash -npm install --global @xgen-ai/cli@0.1.0-rc.6 +npm install --global @xgen-ai/cli xgen --version ``` @@ -30,8 +26,8 @@ Linux/macOS: installer=$(mktemp "${TMPDIR:-/tmp}/xgen-installer.XXXXXX") curl -q --proto '=https' --proto-redir '=https' --tlsv1.2 \ --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo "$installer" \ - https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.6/xgen-installer.sh -sh "$installer" --version v0.1.0-rc.6 + https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.7/xgen-installer.sh +sh "$installer" --version v0.1.0-rc.7 rm -f "$installer" export PATH="$HOME/.local/bin:$PATH" ``` @@ -40,9 +36,9 @@ Windows PowerShell: ```powershell $installer = Join-Path ([System.IO.Path]::GetTempPath()) "xgen-installer-$([Guid]::NewGuid().ToString('N')).ps1" -curl.exe -q --proto "=https" --proto-redir "=https" --tlsv1.2 --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo $installer "https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.6/xgen-installer.ps1" +curl.exe -q --proto "=https" --proto-redir "=https" --tlsv1.2 --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo $installer "https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.7/xgen-installer.ps1" if ($LASTEXITCODE -ne 0) { throw "XGEN installer download failed" } -& $installer -Version v0.1.0-rc.6 +& $installer -Version v0.1.0-rc.7 Remove-Item -LiteralPath $installer $env:Path = "$env:LOCALAPPDATA\XGEN\bin;$env:Path" ``` @@ -72,7 +68,7 @@ xgen --debug xgen --max-model-turns 48 ``` -RC3의 workspace mode는 다음처럼 프로젝트 root와 실행 가능한 개발 도구를 명시적으로 허용한다. +Headless workspace mode는 다음처럼 프로젝트 root와 실행 가능한 개발 도구를 명시적으로 허용한다. ```bash xgen run \ @@ -90,15 +86,14 @@ Process는 shell 없이 실행되지만 별도 `--allow-execute` 전에는 `execute_approval_required`로 pause한다. 허용한 executable과 하위 process는 사용자 OS 권한으로 project code를 실행하므로 이는 sandbox가 아니다. 승인·재개 예시는 [시작하기](docs/getting-started.md)를 따른다. -RC3의 포함 범위와 알려진 한계는 [Developer Preview RC3 후보](docs/development/rc3-release-candidate.md)에 +초기 RC3의 포함 범위와 알려진 한계는 [Developer Preview RC3 후보](docs/development/rc3-release-candidate.md)에 정리되어 있다. 일반 문제는 GitHub Issues, 민감한 취약점은 [보안 정책](SECURITY.md)의 비공개 신고 경로를 사용한다. 대화형 모드는 현재 디렉터리 전체를 workspace catalog로 열되 실제 read/write/execute와 model egress를 -각각 별도로 승인한다. 일반 질문과 후속 질문은 도구 없이 답하며, 최근 요청·답변을 제한된 문맥으로 이어간다. `/model`, `/status`, `/usage`, `/permissions`, `/resume`, `/clear`, `/exit`을 지원하며 줄 끝 -`\`로 여러 줄 goal을 입력한다. 직전 durable completion만 다음 goal의 비신뢰 session context로 이어지고 +각각 별도로 승인한다. 일반 질문과 후속 질문은 도구 없이 답하며, 최근 요청·답변을 제한된 문맥으로 이어간다. `/model`, `/status`, `/usage`, `/permissions`, `/resume`, `/clear`, `/exit`을 지원하며 Alt+Enter로 여러 줄 goal을 입력한다. 입력 기록은 위·아래 화살표로 탐색한다. 직전 durable completion만 다음 goal의 비신뢰 session context로 이어지고 `/clear`가 이를 끊는다. Model의 strict structured proposal을 그대로 화면에 흘리지 않고, 검증된 최종 -summary 전에는 Thinking 표시만 출력한다. `--debug` 또는 pipe 입력에서는 기존 redacted durable progress를 +summary 전에는 진행 상태와 완료된 도구 활동을 표시한다. `--debug` 또는 pipe 입력에서는 기존 redacted durable progress를 출력한다. 모델 응답이 거절되면 최종 답변이 저장되지 않았음을 표시하고 `/resume RUN_ID`를 안내한다. 이미 저장된 @@ -110,13 +105,13 @@ summary 전에는 Thinking 표시만 출력한다. `--debug` 또는 pipe 입력 비용은 선택적으로 단가를 지정했을 때만 추정한다. [사용량 계측 계약](docs/development/model-usage-2026-10-04.md)을 따른다. `model check` 기본형은 선택 profile의 endpoint에 `GET /v1/models` 하나만 보내 기존 자동화 계약을 -유지한다. `--compatibility`를 지정하면 strict structured output POST를 한 번 더 보낸다. `model setup`은 +유지한다. `--compatibility`를 지정하면 선택한 response format의 structured output POST를 한 번 더 보낸다. `model setup`은 두 검증을 모두 통과한 뒤에만 profile을 활성화하며 workspace·Run state는 만들지 않는다. `--workspace` 기본값은 현재 디렉터리다. Headless/CI에서는 원격 HTTPS key를 `XGEN_OPENAI_API_KEY` 또는 `--token-stdin`으로 현재 invocation에만 전달할 수 있다. OS 보안 저장소가 -없는 Linux server에서 평문 파일로 자동 fallback하지 않는다. 현재 호환 경계는 Chat Completions, -strict JSON Schema response와 응답의 exact model ID를 지원하는 서버다. 설치·검증·삭제와 OS별 제약은 +없는 Linux server에서 평문 파일로 자동 fallback하지 않는다. 현재 호환 경계는 Chat Completions, structured JSON proposal과 응답의 exact model ID를 지원하는 서버다. +OpenAI preset은 `json_object`와 `openai` parameter style을 사용한다. 설치·검증·삭제와 OS별 제약은 [시작하기](docs/getting-started.md)와 [모델 온보딩](docs/development/model-onboarding.md)을 따른다. Unix headless `run`의 goal은 최대 65,536 UTF-8 바이트입니다. Windows는 OS command-line diff --git a/THIRD_PARTY_LICENSES.txt b/THIRD_PARTY_LICENSES.txt index 4f07393..ca6c1f2 100644 --- a/THIRD_PARTY_LICENSES.txt +++ b/THIRD_PARTY_LICENSES.txt @@ -6728,7 +6728,7 @@ limitations under the License. License: Apache License 2.0 Used by: -- xgen-cli 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) +- xgen-cli 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) ============================================================================== The LLVM Project is under the Apache License v2.0 with LLVM Exceptions: @@ -7199,16 +7199,16 @@ limitations under the License. License: Apache License 2.0 Used by: -- xgen-adapter-filesystem 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-adapter-process 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-adapter-reference 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-domain 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-local-store 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-policy 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-protocol 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-provider-openai 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-runtime 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) -- xgen-workgraph 0.1.0-rc.6 (https://github.com/PlateerLab/xgen-cli) +- xgen-adapter-filesystem 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-adapter-process 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-adapter-reference 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-domain 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-local-store 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-policy 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-protocol 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-provider-openai 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-runtime 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) +- xgen-workgraph 0.1.0-rc.7 (https://github.com/PlateerLab/xgen-cli) - allocator-api2 0.2.21 (https://github.com/zakarumych/allocator-api2) - anyhow 1.0.104 (https://github.com/dtolnay/anyhow) - async-trait 0.1.92 (https://github.com/dtolnay/async-trait) diff --git a/crates/xgen-cli/src/main.rs b/crates/xgen-cli/src/main.rs index 33ab115..61cbd51 100644 --- a/crates/xgen-cli/src/main.rs +++ b/crates/xgen-cli/src/main.rs @@ -1035,11 +1035,7 @@ fn prompt_provider() -> Result { .collect(); eprintln!("{}", menu.join("\n")); let custom = PROVIDER_PRESETS.len() + 1; - let answer = prompt_line("Provider number: ")?; - let chosen = answer - .trim() - .parse::() - .map_err(|_| ModelCliError::InputUnavailable)?; + let chosen = prompt_number("Provider number (q to cancel): ", custom)?; if chosen == custom { return Ok("custom".to_owned()); } @@ -1442,6 +1438,77 @@ enum ModelCliError { } impl ModelCliError { + const fn recovery_hint(self) -> &'static str { + match self { + Self::Check(error) => match error { + ModelCheckError::AuthenticationRejected | ModelCheckError::InvalidCredential => { + "Run xgen model setup to enter a valid API key locally; never paste keys into chat." + } + ModelCheckError::ModelNotAdvertised | ModelCheckError::InvalidModel => { + "Run xgen model setup and select an exact model ID advertised by the endpoint." + } + ModelCheckError::IncompatibleResponse => { + "Check response format, parameter style and exact response model ID with xgen model setup --help, then run xgen model check --compatibility. Model aliases may return a different snapshot ID." + } + ModelCheckError::RequestRejected => { + "Check the provider's response format and parameter style with xgen model setup --help. Updating a saved profile requires explicit options; then retry xgen model check --compatibility." + } + ModelCheckError::OutputTruncated => { + "Increase --max-output-tokens with xgen model setup, then retry xgen model check --compatibility." + } + ModelCheckError::Timeout + | ModelCheckError::RateLimited + | ModelCheckError::Unavailable => { + "Check provider availability or quota, then retry xgen model check --compatibility. For a slow model, adjust --inference-timeout with xgen model setup." + } + ModelCheckError::InvalidBaseUrl | ModelCheckError::InvalidBasePath => { + "Use xgen model setup --base-url with the API root (for example https://provider.example/v1), not /models or /chat/completions." + } + ModelCheckError::InsecureCredentialTransport + | ModelCheckError::InsecureEndpointTransport => { + "Use HTTPS for remote providers. Plain HTTP is allowed only for a loopback IP address without an API key." + } + ModelCheckError::InvalidResponse => { + "Check that --base-url points to an OpenAI-compatible API root serving GET /models." + } + ModelCheckError::InvalidTokenizer | ModelCheckError::Configuration => { + "Review xgen model setup --help and correct the model configuration before retrying." + } + }, + Self::Profile(ModelProfileError::CredentialNotFound) => { + "The saved API key is unavailable. Run xgen model setup to enter it again locally, or inject XGEN_OPENAI_API_KEY for this process." + } + Self::Profile(ModelProfileError::CredentialStoreUnavailable) => { + "Unlock the OS credential store, or inject XGEN_OPENAI_API_KEY and omit --store-token. No plaintext key file is used." + } + Self::Profile(ModelProfileError::ProfileNotFound) | Self::MissingConfiguration => { + "Run xgen model setup to connect a model, then xgen model list to inspect saved profiles." + } + Self::Profile( + ModelProfileError::ConcurrentModification | ModelProfileError::ProfileCommitUnknown, + ) => { + "Run xgen model list to inspect the saved result before retrying; another process may have changed the profile." + } + Self::Profile(_) => { + "Inspect xgen model list and the private XGEN_CONFIG_HOME directory. Keep existing configuration files until the error is understood." + } + Self::InputUnavailable => { + "Use an interactive terminal for numbered choices, or pass --provider, --base-url and --model explicitly; see xgen model setup --help." + } + Self::InvalidCredential => { + "Enter a non-empty API key locally with xgen model setup; never paste keys into chat." + } + Self::CredentialRequiresHttps => { + "Use HTTPS when supplying an API key. Loopback HTTP connections must not carry a key." + } + Self::InvalidEnvironment + | Self::InvalidInferenceLimits + | Self::InvalidRequestOptions => { + "Review explicit options and XGEN_OPENAI_* environment settings with xgen model setup --help, correct them, and retry." + } + } + } + const fn code(self) -> &'static str { match self { Self::Profile(error) => error.code(), @@ -2222,14 +2289,51 @@ fn prompt_model(models: &[String]) -> Result { for (index, model) in models.iter().enumerate() { eprintln!(" {}) {model}", index + 1); } - let selected = prompt_line("Select model number: ")? - .parse::() - .ok() - .filter(|index| (1..=models.len()).contains(index)) - .ok_or(ModelCliError::InputUnavailable)?; + let selected = prompt_number("Select model number (q to cancel): ", models.len())?; Ok(models[selected - 1].clone()) } +fn prompt_number(prompt: &str, count: usize) -> Result { + read_number( + &mut std::io::stdin().lock(), + &mut std::io::stderr().lock(), + prompt, + count, + ) +} + +fn read_number( + input: &mut impl std::io::BufRead, + output: &mut impl std::io::Write, + prompt: &str, + count: usize, +) -> Result { + if count == 0 { + return Err(ModelCliError::InputUnavailable); + } + loop { + write!(output, "{prompt}") + .and_then(|()| output.flush()) + .map_err(|_| ModelCliError::InputUnavailable)?; + let mut value = String::new(); + if input + .read_line(&mut value) + .map_err(|_| ModelCliError::InputUnavailable)? + == 0 + || value.trim().eq_ignore_ascii_case("q") + { + return Err(ModelCliError::InputUnavailable); + } + if let Ok(selected) = value.trim().parse::() + && (1..=count).contains(&selected) + { + return Ok(selected); + } + writeln!(output, "Enter a number from 1 to {count}, or q to cancel.") + .map_err(|_| ModelCliError::InputUnavailable)?; + } +} + fn print_state_directory_details(error: &PublicRunError) { if let Some(details) = error.state_directory_details() { for line in details.lines() { @@ -2241,17 +2345,23 @@ fn print_state_directory_details(error: &PublicRunError) { fn present_model_command_error(command: &str, error: ModelCliError) -> ExitCode { eprintln!("XGEN model {command}: FAIL"); eprintln!(" reason={}", error.code()); + eprintln!(" recovery: {}", error.recovery_hint()); ExitCode::from(error.exit_code()) } fn present_model_configuration_error(error: ModelCliError) -> ExitCode { eprintln!("XGEN_ERROR code={}", error.code()); + eprintln!(" recovery: {}", error.recovery_hint()); ExitCode::from(error.exit_code()) } fn present_model_check_error(error: ModelCheckError) -> ExitCode { eprintln!("XGEN model check: FAIL"); eprintln!(" reason={}", error.code()); + eprintln!( + " recovery: {}", + ModelCliError::Check(error).recovery_hint() + ); ExitCode::from(error.exit_code()) } @@ -2467,6 +2577,33 @@ mod provider_preset_tests { mod onboarding_tests { use super::*; + #[test] + fn numbered_choices_recover_from_invalid_input_without_restarting_setup() { + // Provider/model menus and a held-out single-item catalog share the same reader. + for count in [PROVIDER_PRESETS.len() + 1, 3, 1] { + let input = format!("invalid\n\n0\n{}\n{count}\n", count + 1); + let mut output = Vec::new(); + assert_eq!( + read_number(&mut input.as_bytes(), &mut output, "Choice: ", count).unwrap(), + count + ); + let output = String::from_utf8(output).unwrap(); + assert_eq!(output.matches("Enter a number").count(), 4); + assert!(!output.contains("invalid")); + } + } + + #[test] + fn numbered_choices_stop_on_cancellation_eof_and_empty_catalog() { + for input in ["", "invalid\n", "q\n", "Q\n"] { + assert!(matches!( + read_number(&mut input.as_bytes(), &mut Vec::new(), "Choice: ", 2), + Err(ModelCliError::InputUnavailable) + )); + } + assert!(read_number(&mut "1\n".as_bytes(), &mut Vec::new(), "Choice: ", 0).is_err()); + } + struct UnavailableCredentials(ModelProfileError); impl ModelCredentialStore for UnavailableCredentials { diff --git a/crates/xgen-cli/tests/environment_onboarding.rs b/crates/xgen-cli/tests/environment_onboarding.rs index d81eef0..3d59304 100644 --- a/crates/xgen-cli/tests/environment_onboarding.rs +++ b/crates/xgen-cli/tests/environment_onboarding.rs @@ -345,6 +345,7 @@ fn model_check_failure_is_redacted_and_does_not_create_local_state() { let stderr = String::from_utf8(output.stderr).expect("stderr should be UTF-8"); assert!(stderr.contains("XGEN model check: FAIL")); assert!(stderr.contains("reason=model_not_advertised")); + assert!(stderr.contains("recovery: Run xgen model setup and select an exact model ID")); assert!(!stderr.contains("RAW-PROVIDER-SENTINEL")); assert!(!stderr.contains(&base_url)); assert!( @@ -369,6 +370,7 @@ fn model_check_reports_actionable_transport_configuration_without_state() { assert!(output.stdout.is_empty()); let stderr = String::from_utf8(output.stderr).expect("stderr should be UTF-8"); assert!(stderr.contains("reason=plaintext_endpoint_must_be_loopback")); + assert!(stderr.contains("recovery: Use HTTPS for remote providers.")); assert!(!stderr.contains("localhost:8000")); assert!( !state.exists(), diff --git a/crates/xgen-cli/tests/model_profiles.rs b/crates/xgen-cli/tests/model_profiles.rs index 053474f..736bc36 100644 --- a/crates/xgen-cli/tests/model_profiles.rs +++ b/crates/xgen-cli/tests/model_profiles.rs @@ -338,6 +338,10 @@ fn token_stdin_is_rejected_for_plaintext_before_network_or_profile_mutation() { assert_eq!(output.status.code(), Some(64)); assert!(output.stdout.is_empty()); assert!(String::from_utf8_lossy(&output.stderr).contains("reason=api_key_requires_https")); + assert!( + String::from_utf8_lossy(&output.stderr) + .contains("recovery: Use HTTPS when supplying an API key.") + ); assert!(!config.exists()); assert!(!state.exists()); } diff --git a/docs/adr/0088-first-use-preview-distribution.md b/docs/adr/0088-first-use-preview-distribution.md new file mode 100644 index 0000000..71d63ae --- /dev/null +++ b/docs/adr/0088-first-use-preview-distribution.md @@ -0,0 +1,71 @@ +# ADR-0088: 기본 preview 설치와 최초 모델 연결 복구 + +- 날짜: 2026-11-19 +- 상태: 채택, rc.7 게시 검증 예정 +- 범위: 일반 배포·CLI 표시. Planner 입력·journal·권한·자동 재시도 계약은 바꾸지 않는다. + +## 문제와 근거 + +npm `latest`가 실행 파일 없는 bootstrap을 가리켜 version 없는 설치로 `xgen`을 실행할 수 없었다. +RC6 뒤의 OpenAI parameter style, TUI idle redraw와 Run capability scope도 아직 배포되지 않았다. +온보딩 문서는 OpenAI preset을 이전 `json_schema`로 안내했고, provider/model 번호를 잘못 입력하면 +전체 설정이 종료됐다. Model 오류는 reason만 출력해서 다음 조치를 찾기 어려웠다. + +이 작업은 최초 사용 흐름의 구현·배포 검증이다. 실제 모델의 장기 작업 완료율을 개선했다고 주장하지 않는다. + +## 결정 + +### 일반: preview의 기본 npm 설치 + +모든 package는 prerelease를 `next`, stable을 `latest`로 게시하고 SRI·provenance·dist-tag를 검증한다. +첫 stable이 없을 때만, 여섯 package 검증을 모두 마친 뒤 launcher의 `latest`를 해당 preview로 지정한다. +Stable이 하나라도 게시됐거나 더 높은 version이 존재하면 preview로 `latest`를 갱신하지 않는다. +잘못된 registry version, 존재하지 않는 candidate/alias, `next` 불일치는 fail-closed한다. +SemVer 비교는 private npm workspace의 고정 `semver@7.8.6` devDependency로 한다. Launcher runtime과 +native binary에는 이 의존성이 들어가지 않는다. `verify-release`의 tag 판정도 같은 parser를 사용한다. + +Platform package는 exact optional dependency이므로 기본 alias를 옮기지 않는다. Alias 갱신 실패는 +동일 release job 재실행으로 복구하며 tarball을 덮어쓰지 않는다. 기존 release concurrency group으로 +publisher를 직렬화한다. 외부 관리자의 동시 dist-tag 변경을 registry 차원에서 원자적으로 막지는 못한다. +GitHub prerelease는 기존처럼 latest release로 지정하지 않으며 native 설치는 exact tag를 사용한다. +기본 npm 설치가 가능해져도 Developer Preview 표시는 유지한다. + +### 일반: 모델 설정의 복구 안내 + +Provider/model 메뉴는 잘못된 번호를 같은 메뉴에서 다시 받는다. `q` 또는 EOF면 기존 +`input_unavailable`/exit64로 종료하며 profile commit은 하지 않는다. 메뉴 복구 때문에 catalog나 probe를 +추가로 호출하지 않는다. API key 입력·보관 경계는 그대로다. + +Model setup/check/configuration 오류는 기존 reason·exit code와 정적 `recovery:` 문장을 함께 출력한다. +인증 재설정, exact model ID, API root, response format·parameter style, provider 가용성·출력/시간 예산을 +안내한다. Provider 응답 원문·실제 endpoint·key를 오류에 추가하지 않는다. 기존 profile의 옵션은 자동 +변경하지 않고 OpenAI profile 갱신 예시를 문서에 제공한다. + +README 첫 화면은 일반 설치·모델 연결·작은 작업·복구 순서로 정리하고 현재 preset/TUI 동작과 맞춘다. +문서 검사는 version을 Cargo workspace에서 파생해 수동으로 RC 번호를 맞추는 지점을 없앤다. + +## 검증과 한계 + +- Rust 800 passed, 0 failed, 4 ignored. Clippy·fmt·release build·license·문서/workflow 검사 통과. +- Pinned graph-tool-call과 compiled CLI를 사용한 Python 검사 162개 통과(10 skipped). Python 3.14의 + 기존 SQLite ResourceWarning은 남지만 실패는 없었다. +- npm 정책 검사 19개: 서로 다른 prerelease 계열, 낮은 stable·build metadata의 hyphen, + 더 높은 preview, 잘못된 metadata, 동일 게시 재실행·SRI/provenance 경계를 검증했다. +- `scripts/smoke-first-use.py`: 격리한 config/state와 실제 CLI에서 provider/model 오입력 뒤 설정 성공, + 실패한 재설정의 기존 profile 보존, compatibility 재검사, Python·JSON 설계 layout과 별도 text layout의 + 읽기→patch→쓰기 승인 재개→테스트 승인 재개→완료 replay를 확인했다. 테스트 실행은 각 1회, + 완료 replay의 model 호출은 0회다. 전체 fixture model POST는 14회이며 유료 모델 호출은 없다. +- 같은 smoke는 RC6 control에서 provider 번호 오입력의 `input_unavailable`로 실패했다. +- npm loopback 설치 smoke에서 version 없는 기본 설치·exact 재설치·삭제를 통과했다. 이 로컬 검사는 + host binary를 사용한 launcher fixture이며 native musl 검증은 platform CI에서 따로 한다. PR gate에서 정책 + 검사·첫 사용 smoke를 실행한다. 게시 후 공개 registry의 기본 설치도 별도로 확인한다. +- 실제 tmux 결과 viewer·승인 smoke 통과(5 fixture model 호출). 기존 rapid resize stress의 간헐적 + 잔상은 이번 작업으로 해결했다고 주장하지 않는다. +- 독립 diff review는 delegate 인증 오류로 실행하지 못했다. Source diff는 로컬에서 직접 검토했다. +- 현재 실제 모델 인증이 없어 유료 모델의 첫 작업 품질 평가는 미실행이다. OS credential store와 + macOS/Windows native terminal의 사용자 실측도 이번 로컬 fixture 검증의 범위 밖이다. + +## 배포 결과 + +rc.7 후보는 RC6 뒤 변경을 함께 포함한다. GitHub/npm 게시와 5개 플랫폼 release 검증 결과는 게시 후 +추가한다. 이 문서의 로컬 통과를 게시 완료나 일반 사용자 작업 성공률의 근거로 해석하지 않는다. diff --git a/docs/development/model-onboarding.md b/docs/development/model-onboarding.md index 77bd97d..7421d41 100644 --- a/docs/development/model-onboarding.md +++ b/docs/development/model-onboarding.md @@ -6,8 +6,8 @@ ## 대화형 설정 터미널에서 URL이나 기존 설정이 없으면 제공자를 먼저 선택하고, 누락된 API key와 model을 묻는다. -DeepSeek preset은 `json_object`와 `thinking disabled`, OpenAI preset은 `json_schema`와 provider 기본 -thinking을 사용한다. Custom endpoint는 URL을 직접 입력한다. API key 입력은 화면에 표시되지 +DeepSeek preset은 `json_object`와 `thinking disabled`, OpenAI preset은 `json_object`, `openai` parameter style과 provider 기본 +thinking을 사용한다. OpenAI style은 `max_completion_tokens`를 보내고 temperature를 생략한다. Custom endpoint는 URL을 직접 입력한다. API key 입력은 화면에 표시되지 않으며 HTTPS provider에서만 허용된다. ```bash @@ -87,9 +87,9 @@ Linux는 `$XDG_CONFIG_HOME/xgen-cli` 또는 `$HOME/.config/xgen-cli`, macOS는 바뀐다. 저장소를 건드리지 않으려면 `XGEN_CONFIG_HOME`을 함께 설정하거나 `run`/`model check`에 `--base-url`, `--model`, `--tokenizer`를 명시한다. -Compatibility probe는 production planner와 같은 proposal JSON Schema와 프로필의 출력 token 예산·inference timeout(ADR-0035, 기본 1024 token·300초)을 사용하고 응답을 production과 같은 document 규칙으로 검증한다. Probe는 model에게 schema 밖의 top-level field를 하나 더 넣으라고 요구하므로, strict schema를 실제로 강제하는 provider만 통과한다. Schema를 받아들이지만 강제하지 못하는 provider(예: 문법 컴파일에 실패하고도 200을 반환하는 서버)는 첫 planner call 대신 `model setup`에서 실패한다. Catalog GET만 더 짧은 timeout을 유지한다. Reasoning을 많이 쓰는 model이 최종 JSON 전에 예산을 소진하면 `provider_output_truncated`로 닫으며, rate limit과 구분한다. +Compatibility probe는 production planner와 같은 proposal JSON Schema와 프로필의 출력 token 예산·inference timeout(ADR-0035, 기본 1024 token·300초)을 사용하고 응답을 production과 같은 document 규칙으로 검증한다. `json_schema` 모드에서는 model에게 schema 밖의 top-level field를 추가하라고 요구해 provider의 strict enforcement를 검사한다. `json_object` 모드에서는 schema 위반을 유도하지 않고 production envelope를 검증한다. Schema를 받아들이지만 강제하지 못하는 provider(예: 문법 컴파일에 실패하고도 200을 반환하는 서버)는 첫 planner call 대신 `model setup`에서 실패한다. Catalog GET만 더 짧은 timeout을 유지한다. Reasoning을 많이 쓰는 model이 최종 JSON 전에 예산을 소진하면 `provider_output_truncated`로 닫으며, rate limit과 구분한다. -`model check`는 기본적으로 기존 계약인 catalog GET만 보낸다. `--compatibility`는 strict JSON Schema +`model check`는 기본적으로 기존 계약인 catalog GET만 보낸다. `--compatibility`는 profile의 response format과 parameter style을 사용하는 Chat Completions POST를 한 번 추가한다. `model setup`은 profile commit 전에 두 요청을 항상 수행한다. ## 로컬 검증 @@ -105,3 +105,22 @@ cargo clippy --workspace --all-targets -- -D warnings 실제 desktop keychain 저장은 사용자 credential을 CI에 넣지 않고 macOS, Windows, Linux desktop에서 수동 release gate로 확인한다. 일반 CI는 in-memory credential fake와 platform compile/link, no-secret file/log regression을 담당한다. 설계와 실패 순서는 [ADR-0032](../adr/0032-model-profiles-and-secure-credential-boundary.md)를 따른다. + +## 연결 실패 후 복구 + +오류의 `reason`과 exit code는 유지하고 `recovery:`에 다음 조치를 표시한다. Provider 원문·key·실제 +endpoint는 진단에 추가하지 않는다. 제공자·model 번호를 잘못 입력하면 같은 메뉴에서 다시 고를 수 있고, +`q`나 EOF는 설정을 중단한다. Compatibility probe가 실패하면 기존 profile을 바꾸지 않는다. + +- `credential_not_found`: `xgen model setup`으로 key를 로컬에서 다시 입력한다. Headless는 secret manager에서 `XGEN_OPENAI_API_KEY`를 process에 주입할 수 있다. +- `model_not_advertised`: `xgen model setup`에서 목록에 있는 정확한 model ID를 고른다. +- `request_rejected` / `chat_completions_incompatible`: response format·parameter style과 응답의 exact model ID를 확인한다. Alias가 다른 snapshot ID를 반환하면 그 snapshot을 목록에서 선택한다. +- `provider_output_truncated`: `xgen model setup --max-output-tokens 4096`처럼 출력 예산을 조정하고 compatibility를 다시 검사한다. +- `timeout` / `rate_limited`: provider 상태·할당량을 확인하고 재검사한다. 느린 model은 `--inference-timeout SECONDS`로 조정할 수 있다. + +이전 OpenAI profile은 저장된 옵션을 자동으로 바꾸지 않으므로 다음처럼 명시적으로 갱신한다. + +```bash +xgen model setup --provider openai --response-format json_object --parameter-style openai +xgen model check --compatibility +``` diff --git a/docs/development/npm-distribution.md b/docs/development/npm-distribution.md index de56921..569b87d 100644 --- a/docs/development/npm-distribution.md +++ b/docs/development/npm-distribution.md @@ -75,6 +75,13 @@ GitHub secret `NPM_TOKEN`에서 publish 단일 step의 `NODE_AUTH_TOKEN`으로 provenance가 있어야 하며 registry metadata에서 SLSA provenance predicate가 확인되지 않으면 job이 실패한다. +최초 stable 게시 전에는 모든 package의 SRI·provenance·`next` 검증이 끝난 뒤 launcher의 `latest`도 +해당 preview로 갱신한다. 이미 stable 또는 더 높은 version이 하나라도 있으면 갱신하지 않는다. +판정은 pinned `node-semver`로 하며 launcher runtime에는 의존성을 추가하지 않는다. +Platform package는 launcher가 exact version으로 참조하므로 `latest`를 갱신할 필요가 없다. +Alias 갱신만 실패해도 동일 release job 재실행으로 끝낼 수 있고 tarball은 바꾸지 않는다. +GitHub Release의 prerelease/latest 분류는 기존대로다. [ADR-0088](../adr/0088-first-use-preview-distribution.md)을 따른다. + ## 부분 실패와 재실행 Platform package를 launcher보다 먼저 게시하므로 중간 실패가 가능하다. 실패한 GitHub Actions job을 diff --git a/docs/development/releasing.md b/docs/development/releasing.md index af6eb00..ae029bd 100644 --- a/docs/development/releasing.md +++ b/docs/development/releasing.md @@ -62,7 +62,7 @@ XGEN Intel macOS binary와 installer 검증 범위에는 영향이 없다. Version을 올린 변경을 먼저 PR로 merge한 뒤 main head에 tag를 만든다. `main`에는 직접 push하지 않는다. ```bash -release_version=0.1.0-rc.6 +release_version=0.1.0-rc.7 release_tag="v$release_version" git fetch origin main git tag -a "$release_tag" origin/main -m "XGEN $release_version" diff --git a/docs/getting-started.md b/docs/getting-started.md index 93a4bf6..122876b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,8 +1,8 @@ # XGEN 설치와 첫 실행 -이 문서는 Developer Preview `v0.1.0-rc.6` release artifact가 게시된 뒤 binary 하나를 설치하고 +이 문서는 Developer Preview `v0.1.0-rc.7` release artifact가 게시된 뒤 binary 하나를 설치하고 OpenAI-compatible model에 연결해 파일 읽기부터 프로젝트 탐색·수정·test/build까지 실행하는 최소 -절차다. RC3 후보는 exact +절차다. 현재 preview는 exact `--allow-file`, `--allow-dir` workspace discovery, atomic write/patch와 host-catalogued shell-free process 실행을 포함한다. Native installer 경로는 소스 개발 절차와 달리 Rust, C compiler, Python, Node.js, SQLite 실행 파일, Docker 또는 XGEN state용 별도 daemon이 필요하지 않다. npm 경로만 @@ -15,7 +15,7 @@ launcher용 Node.js 22.14 이상이 필요하다. 사용할 model endpoint 자 22.14 이상이 있는 지원 OS에서는 아래 순서가 가장 짧다. ```bash -npm install --global --include=optional @xgen-ai/cli@0.1.0-rc.6 +npm install --global --include=optional @xgen-ai/cli xgen --version xgen model setup xgen model check --compatibility @@ -28,6 +28,16 @@ xgen 않으려면 아래 checksum installer를 사용한 뒤 `xgen model setup`부터 같은 순서로 진행한다. API key를 명령행 인자, shell history 또는 일반 설정 파일에 넣지 않는다. +첫 수정은 작은 범위로 요청한다. 예를 들어 `README의 실행 예시 한 곳을 고치고 변경 내용을 보여줘`처럼 +대상을 지정하고, 다음 요청에서 프로젝트의 테스트 명령을 실행한다. 실행 도구는 승인 화면의 +`/allow-executable` 안내를 따라 등록한다. 끝난 뒤 diff와 테스트 결과를 직접 확인한다. + +모델 연결에 실패하면 `reason` 뒤의 `recovery:` 안내를 따른다. 저장된 설정은 `xgen model list`, 실제 +요청 호환성은 `xgen model check --compatibility`로 확인한다. 자세한 오류별 조치는 +[모델 온보딩](development/model-onboarding.md#연결-실패-후-복구)에 있다. +작업 실행 도중 승인 때문에 멈춘 Run은 같은 세션의 `/resume RUN_ID`로 이어간다. 불확정 model 호출은 +자동 재시도하지 않으므로 `xgen recover RUN_ID`로 먼저 상태를 확인한다. + 작업 뒤 `/usage`를 입력하면 추가 API 호출 없이 입력·출력·cached input 토큰을 확인할 수 있다. `xgen usage RUN_ID`는 별도 터미널에서도 상세 JSON을 출력한다. 사용량 기록이 없는 이전 Run이나 provider가 수치를 보내지 않은 호출은 미상이며, 부분 합계는 실제 총비용으로 해석하지 않는다. @@ -51,27 +61,27 @@ Linux binary는 musl target, Windows binary는 static CRT로 빌드한다. macOS ## 설치 -Node.js 22.14 이상이 이미 있는 개발자는 RC3가 npm에 게시된 뒤 다음처럼 exact version을 설치한다. +Node.js 22.14 이상이 이미 있는 개발자는 release가 npm에 게시된 뒤 다음처럼 exact version을 설치한다. `@xgen-ai/cli`에는 lifecycle script가 없고 현재 OS/CPU용 native optional package 하나를 registry에서 함께 설치한다. 설치 중 GitHub download나 source compile을 하지 않는다. ```bash -npm install --global @xgen-ai/cli@0.1.0-rc.6 +npm install --global @xgen-ai/cli@0.1.0-rc.7 xgen --version xgen licenses ``` -Prerelease 최신 채널은 `@xgen-ai/cli@next`, stable은 `@xgen-ai/cli@latest`지만 재현 가능한 설치와 검증에는 -exact version을 사용한다. `npm install --omit=optional`은 실행 binary package를 제거하므로 지원하지 +Prerelease 최신 채널은 `@xgen-ai/cli@next`다. 최초 stable 게시 전에는 `latest`도 검증된 preview를 +가리킨다. Stable 게시 뒤에는 `latest`가 stable을 유지한다. 재현 가능한 설치와 검증에는 exact version을 사용한다. `npm install --omit=optional`은 실행 binary package를 제거하므로 지원하지 않는다. npm 경로에서 platform package를 찾지 못하면 launcher는 다른 binary를 내려받지 않고 종료한다. Node.js를 설치하고 싶지 않거나 GitHub attestation까지 직접 확인하려면 아래 checksum installer 경로를 사용한다. Installer를 먼저 파일로 받은 뒤 검토·실행한다. Installer는 shell profile이나 user PATH를 자동으로 -수정하지 않고 관리자 권한을 요청하지 않는다. RC3는 prerelease이므로 stable release만 가리키는 +수정하지 않고 관리자 권한을 요청하지 않는다. 현재 version은 prerelease이므로 stable release만 가리키는 `releases/latest` 대신 아래 exact tag를 사용한다. 후보 version PR의 merge만으로 artifact가 생기지는 -않으므로 GitHub Release에 `v0.1.0-rc.6`가 게시된 것을 확인한 뒤 실행한다. +않으므로 GitHub Release에 `v0.1.0-rc.7`가 게시된 것을 확인한 뒤 실행한다. Linux/macOS: @@ -79,8 +89,8 @@ Linux/macOS: installer=$(mktemp "${TMPDIR:-/tmp}/xgen-installer.XXXXXX") curl -q --proto '=https' --proto-redir '=https' --tlsv1.2 \ --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo "$installer" \ - https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.6/xgen-installer.sh -sh "$installer" --version v0.1.0-rc.6 + https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.7/xgen-installer.sh +sh "$installer" --version v0.1.0-rc.7 rm -f "$installer" export PATH="$HOME/.local/bin:$PATH" ``` @@ -89,9 +99,9 @@ Windows PowerShell: ```powershell $installer = Join-Path ([System.IO.Path]::GetTempPath()) "xgen-installer-$([Guid]::NewGuid().ToString('N')).ps1" -curl.exe -q --proto "=https" --proto-redir "=https" --tlsv1.2 --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo $installer "https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.6/xgen-installer.ps1" +curl.exe -q --proto "=https" --proto-redir "=https" --tlsv1.2 --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo $installer "https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.7/xgen-installer.ps1" if ($LASTEXITCODE -ne 0) { throw "XGEN installer download failed" } -& $installer -Version v0.1.0-rc.6 +& $installer -Version v0.1.0-rc.7 Remove-Item -LiteralPath $installer $env:Path = "$env:LOCALAPPDATA\XGEN\bin;$env:Path" ``` @@ -124,16 +134,16 @@ xgen licenses installer=$(mktemp "${TMPDIR:-/tmp}/xgen-installer.XXXXXX") curl -q --proto '=https' --proto-redir '=https' --tlsv1.2 \ --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo "$installer" \ - https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.6/xgen-installer.sh -sh "$installer" --version v0.1.0-rc.6 + https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.7/xgen-installer.sh +sh "$installer" --version v0.1.0-rc.7 rm -f "$installer" ``` ```powershell $installer = Join-Path ([System.IO.Path]::GetTempPath()) "xgen-installer-$([Guid]::NewGuid().ToString('N')).ps1" -curl.exe -q --proto "=https" --proto-redir "=https" --tlsv1.2 --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo $installer "https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.6/xgen-installer.ps1" +curl.exe -q --proto "=https" --proto-redir "=https" --tlsv1.2 --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSLo $installer "https://github.com/PlateerLab/xgen-cli/releases/download/v0.1.0-rc.7/xgen-installer.ps1" if ($LASTEXITCODE -ne 0) { throw "XGEN installer download failed" } -& $installer -Version v0.1.0-rc.6 +& $installer -Version v0.1.0-rc.7 Remove-Item -LiteralPath $installer ``` @@ -434,7 +444,7 @@ npm 설치본은 새 exact version을 다시 설치해 업데이트한다. `next 가리킬 수 있으므로 파일럿과 장애 재현에는 사용하지 않는다. ```bash -npm install --global --include=optional @xgen-ai/cli@0.1.0-rc.6 +npm install --global --include=optional @xgen-ai/cli@0.1.0-rc.7 xgen --version ``` diff --git a/npm/package-lock.json b/npm/package-lock.json index c0089a3..88cc7a5 100644 --- a/npm/package-lock.json +++ b/npm/package-lock.json @@ -1,15 +1,31 @@ { "name": "xgen-npm-distribution-workspace", - "version": "0.1.0-rc.6", + "version": "0.1.0-rc.7", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "xgen-npm-distribution-workspace", - "version": "0.1.0-rc.6", + "version": "0.1.0-rc.7", + "devDependencies": { + "semver": "7.8.6" + }, "engines": { "node": ">=22.14.0" } + }, + "node_modules/semver": { + "version": "7.8.6", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz", + "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } } } } diff --git a/npm/package.json b/npm/package.json index 183164d..e2162b6 100644 --- a/npm/package.json +++ b/npm/package.json @@ -1,6 +1,6 @@ { "name": "xgen-npm-distribution-workspace", - "version": "0.1.0-rc.6", + "version": "0.1.0-rc.7", "private": true, "type": "module", "packageManager": "npm@11.19.0", @@ -10,5 +10,8 @@ "scripts": { "check": "node scripts/check.mjs", "test": "node --test tests/*.test.mjs" + }, + "devDependencies": { + "semver": "7.8.6" } } diff --git a/npm/packages/cli/README.md b/npm/packages/cli/README.md index b802acf..15f2c07 100644 --- a/npm/packages/cli/README.md +++ b/npm/packages/cli/README.md @@ -1,17 +1,21 @@ # `@xgen-ai/cli` -`@xgen-ai/cli` is the npm distribution wrapper for the native XGEN CLI. +터미널에서 프로젝트를 읽고 수정하고 테스트하는 XGEN CLI의 native 실행 파일을 설치해. +현재 Developer Preview야. Node.js 22.14 이상이 필요해. ```bash -npm install --global @xgen-ai/cli@0.1.0-rc.6 +npm install --global @xgen-ai/cli xgen --version +cd my-project +xgen ``` -The package selects one exact-version, platform-specific optional dependency and executes the -bundled Rust binary. It does not download code during installation, compile native code, or run an -install lifecycle script. Installing with `--omit=optional` is unsupported because it removes the -native binary package. +첫 실행에서 provider, 숨김 API key와 model을 선택하면 연결을 검증하고 설정을 저장해. +최초 stable 게시 전까지 기본 설치는 검증된 최신 preview를 가리키고, 그 뒤에는 stable을 따라. +Preview 채널은 `@xgen-ai/cli@next`, 고정 설치는 `@xgen-ai/cli@0.1.0-rc.7`이야. -The native binary can also be installed without Node.js from the matching GitHub Release. See the -[XGEN repository](https://github.com/PlateerLab/xgen-cli) for model onboarding and security -boundaries. +현재 OS/CPU의 exact-version optional dependency 하나에 담긴 Rust 실행 파일을 사용해. +설치 script, 추가 download, native compile은 없어. `--omit=optional`은 실행 파일을 빼므로 지원하지 않아. +Node.js 없이 설치하려면 같은 version의 GitHub Release를 사용해. + +모델 연결·권한·복구는 [시작하기](https://github.com/PlateerLab/xgen-cli/blob/main/docs/getting-started.md)를 참고해. diff --git a/npm/packages/cli/package.json b/npm/packages/cli/package.json index b590f98..c1168c1 100644 --- a/npm/packages/cli/package.json +++ b/npm/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@xgen-ai/cli", - "version": "0.1.0-rc.6", + "version": "0.1.0-rc.7", "description": "Local-first XGEN agent CLI and harness", "license": "Apache-2.0", "repository": { @@ -25,11 +25,11 @@ "LICENSE" ], "optionalDependencies": { - "@xgen-ai/cli-linux-x64-musl": "0.1.0-rc.6", - "@xgen-ai/cli-linux-arm64-musl": "0.1.0-rc.6", - "@xgen-ai/cli-darwin-x64": "0.1.0-rc.6", - "@xgen-ai/cli-darwin-arm64": "0.1.0-rc.6", - "@xgen-ai/cli-win32-x64": "0.1.0-rc.6" + "@xgen-ai/cli-linux-x64-musl": "0.1.0-rc.7", + "@xgen-ai/cli-linux-arm64-musl": "0.1.0-rc.7", + "@xgen-ai/cli-darwin-x64": "0.1.0-rc.7", + "@xgen-ai/cli-darwin-arm64": "0.1.0-rc.7", + "@xgen-ai/cli-win32-x64": "0.1.0-rc.7" }, "publishConfig": { "access": "public", diff --git a/npm/scripts/publish.mjs b/npm/scripts/publish.mjs index 85f3e5a..0ee305c 100644 --- a/npm/scripts/publish.mjs +++ b/npm/scripts/publish.mjs @@ -6,6 +6,7 @@ import path from 'node:path'; import { once } from 'node:events'; import { setTimeout as delay } from 'node:timers/promises'; import { fileURLToPath } from 'node:url'; +import semver from 'semver'; import { npmInvocation } from './config.mjs'; import { verifyRelease } from './verify-release.mjs'; @@ -80,6 +81,41 @@ export function validateExistingPublication(remote, report, version, distTag) { ); } +// Before the first stable release, a verified preview is also the default install. +// Once a stable version exists, preview publication must leave `latest` alone. +export function shouldPromotePreview(metadata, version) { + assert(semver.valid(version) && semver.prerelease(version), 'expected a preview version'); + assert(Array.isArray(metadata.versions), 'registry versions are missing'); + assert(metadata.versions.every((value) => typeof value === 'string' && semver.valid(value)), + 'registry contains an invalid version'); + assert(metadata.versions.includes(version), 'preview is not published'); + assert.equal(metadata['dist-tags']?.next, version, 'preview is not the verified next version'); + const latest = metadata['dist-tags']?.latest; + assert(latest === undefined || metadata.versions.includes(latest), 'latest is not published'); + return !metadata.versions.some((value) => !semver.prerelease(value) || semver.gt(value, version)); +} + +async function promotePreview(name, version) { + const result = await run(['view', name, 'versions', 'dist-tags', '--json']); + const metadata = JSON.parse(result.stdout); + if (!shouldPromotePreview(metadata, version)) { + console.log(`npm latest: SKIP ${name}@${version} (stable or newer version exists)`); + return; + } + if (metadata['dist-tags'].latest !== version) { + await run(['dist-tag', 'add', `${name}@${version}`, 'latest']); + } + for (let attempt = 0; attempt < 60; attempt += 1) { + const remote = await remoteMetadata(name, version); + if (remote?.['dist-tags']?.latest === version) { + console.log(`npm latest: PASS ${name}@${version} (developer preview)`); + return; + } + await delay(5000); + } + throw new Error(`${name}@${version} latest promotion did not become verifiable`); +} + async function publishOne(report, version, distTag) { const bytes = await readFile(report.tarball); const localIntegrity = `sha512-${createHash('sha512').update(bytes).digest('base64')}`; @@ -123,10 +159,13 @@ async function publishOne(report, version, distTag) { async function main() { const { directory, tag } = parseArguments(process.argv.slice(2)); const { launcher, reports, version } = await verifyRelease(directory, tag); - const distTag = version.includes('-') ? 'next' : 'latest'; + const distTag = semver.prerelease(version) ? 'next' : 'latest'; for (const report of publicationOrder(reports, launcher.name)) { await publishOne(report, version, distTag); } + // Optional platform dependencies are pinned; only the launcher needs this alias. + // Run this after all package integrity/provenance checks, including on an identical retry. + if (distTag === 'next') await promotePreview(launcher.name, version); } if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) { diff --git a/npm/scripts/smoke.mjs b/npm/scripts/smoke.mjs index 08bc039..cdf737a 100644 --- a/npm/scripts/smoke.mjs +++ b/npm/scripts/smoke.mjs @@ -182,7 +182,7 @@ async function main() { npm_config_fund: 'false', npm_config_update_notifier: 'false', }; - const install = npmInvocation([ + const installOptions = [ 'install', '--global', '--prefix', @@ -191,9 +191,10 @@ async function main() { '--no-audit', '--no-fund', '--loglevel=error', - `${launcher.name}@${version}`, - ]); - await run(install.command, install.args, { env: npmEnvironment }); + ]; + const install = npmInvocation([...installOptions, `${launcher.name}@${version}`]); + const defaultInstall = npmInvocation([...installOptions, launcher.name]); + await run(defaultInstall.command, defaultInstall.args, { env: npmEnvironment }); assert.deepEqual(new Set(requestedTarballs), new Set([launcher.name, specification.packageName])); const root = npmInvocation(['root', '--global', '--prefix', installRoot]); diff --git a/npm/scripts/verify-release.mjs b/npm/scripts/verify-release.mjs index 7161f1b..25cd74e 100644 --- a/npm/scripts/verify-release.mjs +++ b/npm/scripts/verify-release.mjs @@ -1,4 +1,5 @@ import assert from 'node:assert/strict'; +import semver from 'semver'; import { spawn } from 'node:child_process'; import { createHash } from 'node:crypto'; import { lstat, readFile } from 'node:fs/promises'; @@ -123,7 +124,7 @@ export async function verifyRelease(directory, tag) { const { catalog, launcher, version } = await distributionMetadata(); assert.match(tag, /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?$/); assert.equal(tag, `v${version}`); - const distTag = version.includes('-') ? 'next' : 'latest'; + const distTag = semver.prerelease(version) ? 'next' : 'latest'; const launcherTarball = path.join(directory, 'xgen-cli.tgz'); const expectedTarballs = [launcherTarball]; for (const specification of catalog.platforms) { diff --git a/npm/tests/publish-contract.test.mjs b/npm/tests/publish-contract.test.mjs index 09e2638..ce20e4b 100644 --- a/npm/tests/publish-contract.test.mjs +++ b/npm/tests/publish-contract.test.mjs @@ -3,6 +3,7 @@ import test from 'node:test'; import { publicationOrder, + shouldPromotePreview, validateExistingPublication, } from '../scripts/publish.mjs'; @@ -22,6 +23,34 @@ test('platform packages are ordered before the launcher', () => { ); }); +test('latest follows verified previews only until a stable or newer release exists', () => { + for (const [older, candidate] of [ + ['0.0.0-bootstrap.0', '0.1.0-rc.7'], + ['2.0.0-beta.2', '2.0.0-beta.3'], + ]) { + const metadata = { versions: [older, candidate], 'dist-tags': { latest: older, next: candidate } }; + assert.equal(shouldPromotePreview(metadata, candidate), true); + assert.equal(shouldPromotePreview({ ...metadata, 'dist-tags': { latest: candidate, next: candidate } }, candidate), true); + for (const stable of ['0.0.1', '1.0.0+build-with-hyphen']) { + assert.equal(shouldPromotePreview({ ...metadata, versions: [...metadata.versions, stable] }, candidate), false); + } + assert.equal(shouldPromotePreview({ ...metadata, versions: [...metadata.versions, '3.0.0-rc.1'] }, candidate), false); + } +}); + +test('preview promotion fails closed on incomplete or inconsistent registry metadata', () => { + const version = '1.0.0-rc.1'; + const metadata = { versions: [version], 'dist-tags': { next: version } }; + for (const invalid of [ + {}, + { ...metadata, versions: [] }, + { ...metadata, versions: [version, 'invalid'] }, + { ...metadata, 'dist-tags': { next: '0.9.0-rc.1' } }, + { ...metadata, 'dist-tags': { next: version, latest: '0.9.0' } }, + ]) assert.throws(() => shouldPromotePreview(invalid, version)); + assert.throws(() => shouldPromotePreview(metadata, '1.0.0')); +}); + test('publication order requires exactly one launcher', () => { assert.throws( () => publicationOrder([{ name: '@xgen-ai/cli-linux-x64-musl' }], '@xgen-ai/cli'), diff --git a/scripts/check-npm-distribution-workflow.sh b/scripts/check-npm-distribution-workflow.sh index a49fa13..43005d5 100755 --- a/scripts/check-npm-distribution-workflow.sh +++ b/scripts/check-npm-distribution-workflow.sh @@ -148,8 +148,10 @@ for fragment in ( fail(f"npm package smoke is missing lifecycle verification: {fragment}") install_invocation = "await run(install.command, install.args, { env: npmEnvironment });" -if smoke_text.count(install_invocation) != 2: - fail("npm package smoke must install the exact package twice") +if smoke_text.count(install_invocation) != 1: + fail("npm package smoke must install the exact package") +if smoke_text.count("await run(defaultInstall.command, defaultInstall.args, { env: npmEnvironment });") != 1: + fail("npm package smoke must also install the default package") print("npm release workflow contract: PASS") PY diff --git a/scripts/check-rc3-public-docs.sh b/scripts/check-rc3-public-docs.sh index e4cd890..48123a2 100644 --- a/scripts/check-rc3-public-docs.sh +++ b/scripts/check-rc3-public-docs.sh @@ -8,8 +8,10 @@ repo_root=$(CDPATH= cd -- "$script_dir/.." && pwd -P) python3 - "$repo_root" <<'PY' from pathlib import Path import sys +import tomllib root = Path(sys.argv[1]) +version = tomllib.loads((root / "Cargo.toml").read_text(encoding="utf-8"))["workspace"]["package"]["version"] getting_started = (root / "docs/getting-started.md").read_text(encoding="utf-8") pilot = (root / "docs/development/rc3-developer-preview-pilot.md").read_text( encoding="utf-8" @@ -34,7 +36,7 @@ require( getting_started, ( "## 5분 빠른 시작", - "@xgen-ai/cli@0.1.0-rc.6", + f"@xgen-ai/cli@{version}", "xgen model setup", "xgen model check --compatibility", "## 업데이트와 RC2 rollback", diff --git a/scripts/smoke-first-use.py b/scripts/smoke-first-use.py new file mode 100644 index 0000000..e4771fa --- /dev/null +++ b/scripts/smoke-first-use.py @@ -0,0 +1,174 @@ +#!/usr/bin/env python3 +"""Check fresh model setup, editing, test execution and approval recovery with a local fixture. + +This validates CLI plumbing, not real model quality. All profiles and Run state are isolated. +""" + +import argparse +from collections import deque +import hashlib +import http.server +import json +import os +from pathlib import Path +import re +import subprocess +import sys +import tempfile +import threading + +TIMEOUT = 60 + + +def completion(): + return {"formatVersion": 1, "kind": "completion_candidate", "steps": [], "summary": "Fixture verified."} + + +def plan(key, capability, arguments, version="1.0.0"): + return {"formatVersion": 1, "kind": "plan", "summary": "", "steps": [{ + "key": key, "objective": key, "dependsOn": [], + "capability": {"capabilityId": capability, "contractVersion": version}, "arguments": arguments, + }]} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--binary", type=Path, default=Path("target/debug/xgen")) + args = parser.parse_args() + binary = args.binary.resolve(strict=True) + responses, requests = deque(), [] + + class Model(http.server.BaseHTTPRequestHandler): + def log_message(self, *_): + pass + + def send(self, value): + body = json.dumps(value).encode() + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def do_GET(self): + assert self.path == "/v1/models" + self.send({"data": [{"id": name} for name in ["alpha-fixture", "beta-fixture"]]}) + + def do_POST(self): + assert self.path == "/v1/chat/completions" + body = json.loads(self.rfile.read(int(self.headers["Content-Length"]))) + requests.append(body) + self.send({"model": body["model"], "choices": [{"index": 0, + "message": {"role": "assistant", "content": json.dumps(responses.popleft())}, + "finish_reason": "stop"}]}) + + server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Model) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + with tempfile.TemporaryDirectory(prefix="xgen-first-use-") as temporary: + root = Path(temporary) + environment = {key: value for key, value in os.environ.items() + if not key.startswith(("XGEN_", "XGENY_"))} + environment.update(XGEN_CONFIG_HOME=str(root / "config"), XGEN_STATE_HOME=str(root / "state"), + NO_PROXY="127.0.0.1", no_proxy="127.0.0.1") + endpoint = f"http://127.0.0.1:{server.server_port}/v1" + + def run(*arguments, expected=0, cwd=root): + result = subprocess.run([str(binary), *arguments], cwd=cwd, env=environment, + capture_output=True, text=True, timeout=TIMEOUT) + assert result.returncode == expected, (arguments[0], result.returncode, result.stderr) + return result + + responses.append(completion()) + if os.name == "posix": + import pty + master, slave = pty.openpty() + try: + # Both provider and model menus recover without restarting setup or refetching. + child = subprocess.Popen([str(binary), "model", "setup"], cwd=root, env=environment, + stdin=slave, stdout=slave, stderr=slave) + os.write(master, f"0\n6\n{endpoint}\ninvalid\n2\n".encode()) + import select + import time + output = bytearray() + deadline = time.monotonic() + TIMEOUT + while child.poll() is None: + assert time.monotonic() < deadline, "interactive setup timed out" + if select.select([master], [], [], 0.1)[0]: + output.extend(os.read(master, 65536)) + while select.select([master], [], [], 0.1)[0]: + output.extend(os.read(master, 65536)) + assert child.returncode == 0, output.decode(errors="replace") + assert output.count(b"Enter a number") == 2 + finally: + if child.poll() is None: + child.kill() + child.wait(timeout=TIMEOUT) + os.close(master) + os.close(slave) + else: + run("model", "setup", "--base-url", endpoint, "--model", "beta-fixture") + assert len(requests) == 1 + profile = root / "config/model-profiles.json" + original = profile.read_bytes() + assert not (root / "state").exists() + failed = run("model", "setup", "--model", "missing-fixture", expected=65) + assert "reason=model_not_advertised" in failed.stderr and "recovery:" in failed.stderr + assert profile.read_bytes() == original + responses.append(completion()) + run("model", "check", "--compatibility") + python = str(Path(sys.executable).resolve()) + + # Two design layouts and an independent text layout use identical capability contracts. + for index, (filename, before, after, check) in enumerate([ + ("answer.py", "def answer():\n return 41\n", "def answer():\n return 42\n", + "from answer import answer; assert answer() == 42"), + ("settings.json", '{"enabled": false}\n', '{"enabled": true}\n', + 'import json; assert json.loads(Path("settings.json").read_text())["enabled"] is True'), + ("note.txt", "draft\n", "reviewed\n", 'assert Path("note.txt").read_text() == "reviewed\\n"'), + ]): + workspace = root / f"project-{index}" + workspace.mkdir() + source = workspace / filename + source.write_text(before) + (workspace / "verify.py").write_text( + 'from pathlib import Path\n' + check + '\n' + 'p = Path("verified.txt"); p.write_text(p.read_text() + "ok\\n" if p.exists() else "ok\\n")\n') + responses.extend([ + plan("inspect", "xgeny.fs/read-text", {"path": filename}), + plan("update", "xgeny.fs/apply-patch", {"path": filename, + "expectedDigest": "sha256:" + hashlib.sha256(before.encode()).hexdigest(), + "edits": [{"oldText": before, "newText": after}]}, "2.0.0"), + plan("test", "xgeny.process/execute", {"executable": "python", "args": ["verify.py"], + "cwd": ".", "env": {}, "timeoutMs": 30000, "maxOutputBytes": 4096}), + completion(), + ]) + common = ["--workspace", str(workspace), "--allow-dir", ".", + "--allow-executable", f"python={python}", "--allow-remote-model-egress", "--allow-read"] + first = run("run", *common, "Update the file and run verify.py.", expected=10) + assert "reason=write_approval_required" in first.stderr + run_id = re.search(r"run_id=(\S+)", first.stderr)[1] + assert source.read_text() == before + second = run("resume", run_id, *common, "--allow-write", expected=10) + assert "reason=execute_approval_required" in second.stderr + assert source.read_text() == after + assert not (workspace / "verified.txt").exists() + run("resume", run_id, *common, "--allow-write", "--allow-execute") + assert (workspace / "verified.txt").read_text() == "ok\n" + calls = len(requests) + run("resume", run_id) + assert len(requests) == calls + assert (workspace / "verified.txt").read_text() == "ok\n" + run("usage", run_id) + assert not responses + assert profile.read_bytes() == original + print(f"first-use fixture: PASS (fresh setup, failed setup preserved, 3 edit/test/resume layouts; {len(requests)} model fixture calls, no live LLM)") + finally: + server.shutdown() + server.server_close() + thread.join(timeout=TIMEOUT) + + +if __name__ == "__main__": + main() From d7cf54e28261a6bede3a9978a85aaf2fa1ee6ac5 Mon Sep 17 00:00:00 2001 From: Son Seong Jun <166786347+SonAIengine@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:22:48 +0900 Subject: [PATCH 2/2] =?UTF-8?q?=EC=B2=AB=20=EC=8B=A4=ED=96=89=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=EC=9D=98=20=EA=B5=AC=EB=B2=84=EC=A0=84=20strict=20?= =?UTF-8?q?=EC=A0=84=EC=9A=A9=20=EC=95=88=EB=82=B4=EB=A5=BC=20=ED=98=84?= =?UTF-8?q?=EC=9E=AC=20=EC=97=B0=EA=B2=B0=20=EC=98=B5=EC=85=98=EC=97=90=20?= =?UTF-8?q?=EB=A7=9E=EC=B6=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/getting-started.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 122876b..eec5b43 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -159,13 +159,13 @@ Checksum은 전송 손상을 탐지하지만 같은 release publisher 자체를 ## 로컬 모델 연결 -현재 검증된 기준은 vLLM의 OpenAI-compatible Chat Completions endpoint다. 다음 조건을 모두 만족해야 -실제 planner call이 통과한다. +로컬·원격 OpenAI-compatible Chat Completions endpoint를 연결한다. 다음 조건을 모두 만족해야 +실제 planner call이 통과한다. Provider별 검증 범위는 아래 표를 따른다. - base URL이 bare host가 아니라 API root를 가리킨다. 대부분 `/v1`이지만 provider가 자기 API를 다르게 번호 붙이면 그 경로를 쓴다(예: `/api/paas/v4`). 끝에 `/`가 붙어도 같게 취급한다. - plaintext HTTP는 `127.0.0.1` 또는 `::1` literal loopback만 사용한다. -- server가 strict JSON Schema response format을 지원한다. +- server가 선택한 response format(`json_schema` 또는 `json_object`)을 지원하고 production proposal을 반환한다. - response의 `model` 문자열이 설정한 served model ID와 정확히 같다. - custom CA, ambient proxy, redirect와 자동 retry에 의존하지 않는다. @@ -255,7 +255,7 @@ XGEN_OPENAI_API_KEY="$(secret-manager-command)" xgen model check --compatibility Credential은 `--token-stdin`, `XGEN_OPENAI_API_KEY`, profile secure store 순서다. Stored credential은 profile URL과 최종 URL이 정확히 같을 때만 쓴다. -`xgen model setup`은 bounded `GET /v1/models` 뒤 실제 strict JSON Schema +`xgen model setup`은 bounded `GET /v1/models` 뒤 profile의 response format·parameter style로 `POST /v1/chat/completions`를 보내 두 요청이 모두 성공한 profile만 commit한다. Workspace, SQLite 또는 Run state를 만들지 않는다. `model check` 기본형은 기존 자동화 호환성을 위해 catalog GET만 수행하고, `--compatibility`를 지정하면 같은 inference probe를 추가한다. Redirect, retry와 ambient proxy는 @@ -335,7 +335,7 @@ xgen run ` "README를 읽고 핵심을 요약해줘." ``` -RC3에서는 사용자가 파일명을 미리 나열하지 않고 선택한 workspace directory를 탐색하고 별도 승인 아래 +Workspace mode에서는 사용자가 파일명을 미리 나열하지 않고 선택한 workspace directory를 탐색하고 별도 승인 아래 atomic write할 수 있다. ```bash @@ -354,7 +354,7 @@ xgen run \ directory 밖의 exact file만 `--allow-file Cargo.toml`로 추가한다. 미완료 재개에는 원래와 동일한 `--allow-dir`/`--allow-file` 집합을 다시 제공해야 한다. -RC3에서는 test/build용 executable도 absolute path로 명시할 수 있다. 경로를 model에 보내지는 않으며 +Workspace mode에서는 test/build용 executable도 absolute path로 명시할 수 있다. 경로를 model에 보내지는 않으며 logical ID만 planning constraint에 노출한다. ```bash @@ -432,7 +432,7 @@ xgen resume run-0123456789abcdef0123456789abcdef ``` 상세 재개 절차는 [Public local run/resume prototype](development/public-local-run-resume.md)을 따른다. -RC3는 workspace discovery, bounded atomic text write/patch와 명시적 shell-free process 실행을 +현재 preview는 workspace discovery, bounded atomic text write/patch와 명시적 shell-free process 실행을 제공한다. Browser와 MCP는 후속 범위이므로 현 상태를 Claude Code/Codex 전체 기능과 동일하다고 해석하지 않는다. Discovery 경계는 [Workspace filesystem discovery](development/workspace-filesystem-discovery.md), write 경계는 @@ -452,11 +452,11 @@ Native 설치본은 위 installer를 같은 install directory에 exact tag로 binary의 checksum, version과 protocol을 먼저 확인하고 성공한 파일만 같은 directory rename으로 교체한다. 실행 중인 `xgen`를 교체하지 말고 모든 session을 종료한 뒤 업데이트한다. -RC3 npm package만 문제가 있고 같은 RC3 GitHub Release가 정상이라면 npm 설치본을 제거하고 exact RC3 -native installer로 전환할 수 있다. 두 채널은 같은 release binary를 담으므로 이는 제품 version +npm package만 문제가 있고 같은 version의 GitHub Release가 정상이라면 npm 설치본을 제거하고 동일 +version의 native installer로 전환할 수 있다. 두 채널은 같은 release binary를 담으므로 이는 제품 version rollback이 아니라 설치 채널 전환이다. -제품 version을 RC2로 되돌려야 하면 기존 RC3 binary와 state를 지우거나 덮어쓰지 말고 RC2를 별도 +이전 RC3→RC2 전환 예시: 제품 version을 RC2로 되돌려야 하면 기존 RC3 binary와 state를 지우거나 덮어쓰지 말고 RC2를 별도 user-owned directory에 설치한다. RC3가 만든 Run을 RC2로 열거나 resume하는 것은 지원하지 않는다. RC2에서 시작해 아직 model egress가 필요한 Run은 원래 RC2 binary로 마치고, 새 작업은 RC3에서 새 Run으로 시작한다. 완료된 RC2 Run은 RC3에서 offline replay할 수 있다. @@ -514,15 +514,15 @@ profile 저장소를 격리하려면 `XGEN_CONFIG_HOME`을 따로 설정한다. | `xgen: command not found` | npm global bin 또는 native install directory가 현재 `PATH`에 있는지 확인하고 새 terminal에서 다시 실행한다. | | `unsupported_platform` 또는 platform package 없음 | 지원 OS/architecture와 Node.js version을 확인하고 `--omit=optional` 없이 exact package를 재설치한다. | | Installer가 destination을 거부 | 관리자 공용 경로 대신 user-owned directory를 사용하고 symbolic link/reparse point나 broadly writable directory를 제거하지 말고 다른 빈 경로를 선택한다. | -| PowerShell에서 installer 차단 | Script를 먼저 검토한다. 현재 process 한정 execution-policy 예외는 조직 정책이 허용할 때만 사용한다. SmartScreen 경고는 RC3에 Authenticode가 없기 때문이다. | +| PowerShell에서 installer 차단 | Script를 먼저 검토한다. 현재 process 한정 execution-policy 예외는 조직 정책이 허용할 때만 사용한다. 현재 preview에는 Authenticode가 없어 SmartScreen 경고가 나타날 수 있다. | | `base_url_must_name_the_api_root` | base URL이 host만 있고 경로가 없다. `https://api.openai.com`이 아니라 `https://api.openai.com/v1`처럼 API root까지 적는다. 어떤 경로인지는 provider 문서가 정한다. | | `credential_store_unavailable` | 평문 저장 fallback은 없다. Secret manager 출력을 `--token-stdin`이나 현재 process의 `XGEN_OPENAI_API_KEY`로 전달한다. | -| `chat_completions_incompatible` | Provider가 strict JSON Schema 요청을 받아들였지만 실제로 강제하지 않았거나 envelope 밖으로 답했다. Probe는 production planner와 같은 proposal schema를 보내고 schema 밖 field를 하나 더 요구하므로, 문법을 강제하지 못하는 서버는 planner call 대신 `model setup`에서 여기서 닫힌다. 이는 의도된 동작이다. Probe 스키마는 구조만 강제하므로(ADR-0037) `additionalProperties`, `required`, `enum`, `const`를 강제하지 못하는 provider가 여기서 걸린다. | -| `model_not_advertised` 또는 compatibility 실패 | URL이 bare host가 아니라 provider의 API root인지, exact served model ID와 strict JSON Schema Chat Completions 지원을 확인한다. Redirect나 자동 retry에 의존하지 않는다. | +| `chat_completions_incompatible` | 선택한 response format·parameter style과 응답의 exact model ID를 확인한다. `json_schema`에서는 strict enforcement도 검사한다. 기존 OpenAI profile은 `xgen model setup --response-format json_object --parameter-style openai`로 갱신하고 compatibility를 다시 검사한다. | +| `model_not_advertised` 또는 compatibility 실패 | URL이 bare host가 아니라 provider의 API root인지, exact served model ID와 선택한 structured response format 지원을 확인한다. Redirect나 자동 retry에 의존하지 않는다. | | `model setup`/`model check`의 `timeout` | Inference probe는 production planner와 같은 wall-clock 예산을 쓴다. 로컬 model은 첫 로드가 크기와 disk cache 상태에 따라 수십 초 걸릴 수 있으므로 endpoint에서 model을 한 번 warm-up한 뒤 재시도한다. | | `provider_output_truncated` | Probe나 planner 응답이 출력 token 예산에서 잘렸다. Reasoning을 많이 쓰는 model은 최종 JSON 전에 예산을 소진할 수 있으므로 model의 thinking 설정이나 profile의 출력 예산을 조정한다. Rate limit이 아니므로 재시도로 해결되지 않는다. | | `proposal_rejected.*` | 뒤의 class가 Core가 제안을 거부한 이유다. `capability_unavailable`/`capability_unsupported`는 허용하지 않은 capability 선택, `invocation_invalid`는 scope 밖 인자나 스키마 위반, `tool_call_budget_exhausted`는 예산 소진, `repeated_finished_action`은 방금 끝난 읽기를 같은 인자로 다시 제안한 경우다. 예산 소진이 아닌 거절은 연속 2번까지 자동으로 다시 묻고 세 번째에 멈추며, 다시 물을 때 거절 이유를 함께 준다. `repeated_finished_action`만은 따로 연속 8번까지 다시 묻는다([ADR-0061](adr/0061-rejected-response-retry.md), [ADR-0064](adr/0064-planning-feedback.md), [ADR-0067](adr/0067-step-arguments-and-repeat-limit.md)). Class는 Core 판정이며 model 출력 원문이 아니다. | -| `model_rejected.*` | 뒤의 class는 journal의 model call settlement와 같은 값이다. `planner_invalid_response`는 provider가 strict JSON Schema를 지키지 않은 응답(문법 미지원·미적용), `provider_limit`은 출력 예산·요청 크기 초과, `provider_rejected`는 4xx 거부다. `planner_invalid_response`만 연속 2번까지 자동으로 다시 묻는다(ADR-0061). Class는 Core 판정이며 model 출력 원문이 아니다. | +| `model_rejected.*` | 뒤의 class는 journal의 model call settlement와 같은 값이다. `planner_invalid_response`는 provider가 strict JSON Schema를 지키지 않은 응답(문법 미지원·미적용), `provider_limit`은 출력 예산·요청 크기 초과, `provider_rejected`는 4xx 거부다. `planner_invalid_response`와 출력이 잘린 응답은 연속 2번까지 자동으로 다시 묻는다(ADR-0061, ADR-0073). Class는 Core 판정이며 model 출력 원문이 아니다. | | `configuration_mismatch` | 원래 workspace, file/directory scope, executable와 model profile binding(inference timeout·출력 예산 포함)으로 resume한다. 자동 대체하지 말고 필요하면 새 Run을 시작한다. | | `model_call_unknown.timeout`이 planner 호출마다 반복 | 프로필의 inference timeout이 model·hardware에 비해 짧다. 로컬 27B는 호출당 60초 안팎이 걸리므로 `--inference-timeout`을 올린다. | | `model_call_unknown.transport_unavailable` / `.interrupted` | 요청이 전송됐을 수 있으나 결과를 못 받았다(연결 끊김) 또는 process가 응답 전에 끝났다. 자동 replay하지 않으므로 endpoint 상태를 확인한 뒤 `resume`한다. | @@ -543,5 +543,5 @@ project는 민감정보가 없는 최소 fixture로 새로 만든다. 세부 범 - Run state에는 goal과 bounded tool output이 포함될 수 있으므로 state root 전체를 민감 데이터로 취급한다. - SQLite는 binary에 내장된 local library다. SQLite server나 별도 database 설치가 필요하지 않다. - 전송 여부가 불확정한 model/effect는 Unknown으로 보존하며 자동 replay하지 않는다. -- macOS/Windows RC3 binary에는 OS code signing/notarization이 없다. Checksum과 GitHub attestation은 +- macOS/Windows preview binary에는 OS code signing/notarization이 없다. Checksum과 GitHub attestation은 전송 무결성과 build provenance를 확인하지만 OS publisher 서명을 대신하지 않는다.