ํ๋ก์ ํธ root์์ subcommand ์์ด ์คํํ๋ค. TTY์์ profile์ด ์์ผ๋ฉด ์ ๊ณต์ ์ ํ, ์จ๊น API key ์ ๋ ฅ, model ์ ํ๊ณผ ์ฐ๊ฒฐ ๊ฒ์ฆ์ ์งํํ๋ค. DeepSeek์ OpenAI๋ preset์ผ๋ก URL๊ณผ wire ์ต์ ์ ์ฑ์ฐ๋ฉฐ, ๋ค๋ฅธ OpenAI-compatible endpoint๋ URL์ ์ง์ ์ ๋ ฅํ๋ค. ์ ์ฅ๋ ์ค์ ์ ๋ค์ ์คํ๋ถํฐ ์ฌ์ฌ์ฉํ๋ค.
cd my-project
xgenAPI key๋ OS credential store์ ์ ์ฅํ๋ค. ์ ์ฅ์๋ฅผ ์ธ ์ ์์ผ๋ฉด ์จ๊น ์
๋ ฅํ key๋ ํ์ฌ process์
๋ฉ๋ชจ๋ฆฌ์๋ง ๋๊ณ ๋ค์ ์คํ ๋ ๋ค์ ๋ฌป๋๋ค. ํ๋ฌธ key file์ด๋ tool process ํ๊ฒฝ๋ณ์๋ก ์ฎ๊ธฐ์ง ์๋๋ค.
์๋ํ์ --store-token์ ์ฌ์ ํ ์ ์ฅ ์คํจ๋ฅผ ์ค๋ฅ๋ก ๋ฐํํ๋ค.
๊ธฐ๋ณธ approval mode๋ ๋ชจ๋ ask๋ค. Model prompt์๋ ํ์ฌ goal, ์ ํ๋ ์ด์ ์์ฒญยท๋ต๋ณ๊ณผ ์ดํ tool
observation์ด ํฌํจ๋ ์ ์๋ค. Read, write์ process execute๋ ๊ฐ๊ฐ ๋ณ๋๋ก ๋ฌป๋๋ค.
ํ goal์ ์ฒ๋ฆฌํ๋ ๋์ ์น์ธํ ์ข
๋ฅ๋ ์ดํ continuation์์๋ ์ ์งํ๋ฉฐ, ๋ค์ goal์ด๋ ๋ช
์์ ์ธ
/resume์์๋ ๋ค์ ๊ธฐ๋ณธ approval mode๋ฅผ ์ ์ฉํ๋ค. deny๋ ๊ณ์ ์คํ์ ์ฐจ๋จํ๋ค.
์น์ธ prompt์ ๋ต์ ์ธ ๊ฐ์ง๋ค(ADR-0058). y๋ ์ง๊ธ์ฒ๋ผ ์ด๋ฒ
goal์๋ง ํ์ฉํ๋ค. a๋ ๊ทธ ์ข
๋ฅ๋ฅผ ๋จ์ REPL session ๋์ allow๋ก ๋ฐ๊พธ๋ฉฐ
/permissions KIND allow์ ๊ฐ๋ค. ๋ฐ๋ ์ฌ์ค๊ณผ ๋๋๋ฆฌ๋ ๋ช
๋ น์ ํ ์ค๋ก ํ์ํ๋ค. ๊ทธ ๋ฐ์ ์
๋ ฅ์ ๊ฑฐ์ ์ด๋ค.
Session ํ์ฉ์ ํ์ผ์ ์ ์ฅํ์ง ์๊ณ process๊ฐ ๋๋๋ฉด ์ฌ๋ผ์ง๋ค.
xgen --trust๋ ๋ค ์ข
๋ฅ๋ฅผ ๋ชจ๋ allow๋ก ๋ ์ฑ session์ ์์ํด ์น์ธ์ ๋ฌป์ง ์๋๋ค
(ADR-0059). ์์ํ ๋ ํ ์ค๋ก ์๋ฆฌ๊ณ , /permissions KIND ask๋ก ์ผ๋ถ๋ฅผ ๋ค์
๋ฌป๊ฒ ํ ์ ์๋ค. ๊ธฐ๋ก, Changes ํ์, Ctrl+C, /resume์ ๊ฐ๋ค.
์ ๋ขฐ ๋ชจ๋๋ ์ฌ์ฉ์์ shell(SHELL์ด bashยทzshยทsh๋ฉด ๊ทธ๊ฒ, ์๋๋ฉด PATH์ bashโzshโsh, Windows๋
pwshโpowershell)๋ catalog์ ๋ฃ๋๋ค(ADR-0060). ๋ชจ๋ธ์ ์ด๊ฒ์ผ๋ก
ํ์ดํ์ catalog์ ์๋ ๋ช
๋ น์ ์คํํ๋ค.
์ ๋ขฐ ๋ชจ๋์ goal๋น model turn ๊ธฐ๋ณธ๊ฐ์ 24๊ฐ ์๋๋ผ 96์ด๋ค(ADR-0062).
--max-model-turns๋ฅผ ์ฃผ๋ฉด ๊ทธ ๊ฐ์ด ์ฐ์ ํ๋ค.
์ ๋ขฐ ๋ชจ๋๋ goal ๋ค์ workspace ์ ๋ ๊ฒฝ๋ก, home, workspace ๋ฐ์ shell๋ก ๊ฐ๋ผ๋ ์๋ด ํ ๋จ๋ฝ์ ๋ถ์ธ๋ค
(ADR-0063).
xgen> ํ๋ก์ ํธ ๊ตฌ์กฐ๋ฅผ ๋ณด๊ณ ํ
์คํธ ์คํจ๋ฅผ ์์ ํด์ค.
Allow sending the goal, session context, and tool observations to the model? [y/a/N] y
Thinkingโฆ ยท 2s
Allow read for this durable continuation? [y/a/N] a
read allowed for this session (/permissions read ask to undo)
์ค ๋์ unescaped \๋ฅผ ์ฐ๋ฉด ๋ค์ ์ค์ ๊ฐ์ goal๋ก ์
๋ ฅํ๋ค.
xgen> src๋ฅผ ํ์ํ๊ณ \
...> ์คํจํ ํ
์คํธ๋ง ์์ ํด์ค.
/model [PROFILE]
/status
/permissions
/permissions model|read|write|execute ask|allow|deny
/resume [RUN_ID]
/clear
/exit
allow๋ ํ์ฌ REPL session์์ ์ฌ์ฉ์๊ฐ ๋ช
์ํ ์ ํ์ด๋ค. Process executable์ PATH์์ ๋ฐ๊ฒฌํ ๊ณ ์ ๋
๊ณตํต ๊ฐ๋ฐ ๋๊ตฌ allowlist์ absolute native executable๋ง catalogํ๋ค. /permissions๋ model์ ๋ณด์ด๋
logical ID๋ง ์ถ๋ ฅํ๋ฉฐ host path๋ ์ถ๋ ฅํ์ง ์๋๋ค. Catalog๋ ์คํ ๊ถํ์ด ์๋๊ณ , ์คํ์ ๋ณ๋ approval๊ณผ
Core authorization์ ๊ฑฐ์น๋ค. Catalog snapshot์ ์ฒซ ์ค์ goal์์ ๋ง๋ค์ด ๊ฐ์ REPL process์ resume์
์ฌ์ฌ์ฉํ๋ฉฐ, ์ ํ๋ binary๋ ๋งค ์คํ ์ง์ ์ ๋ค์ ๊ฒ์ฆํ๋ค.
ํ goal์ ํ๋์ durable Run์ด๋ค. ์ผ๋ฐ ์ง๋ฌธ์ด๋ ์ด์ ์ค๋ช
์ ๋ํ ํ์ ์ง๋ฌธ์ ๋๊ตฌ ์คํ ์์ด ๋ตํ ์ ์๋ค.
์ด ๊ฒฝ์ฐ /status๋ responded๋ฅผ ํ์ํ๊ณ ํ์ผยทprocess ์คํ ์น์ธ์ ๋ฌป์ง ์๋๋ค. ๋๊ตฌ Step์ ๊ณํํ Run์
๋ํ ์๋ต์ผ๋ก ์ข
๋ฃํ ์ ์๊ณ , ๊ธฐ์กด๋๋ก Receipt ๊ฒ์ฆ ๋ค ์์
์๋ฃ ์๋ต์ ์ถ๋ ฅํ๋ค.
์ต๊ทผ ์์ฒญยท๋ต๋ณ์ ์ต๋ 8 turn, JSON ๊ธฐ์ค 12 KiB์ ๋น์ ๋ขฐ context๋ก ์ด์ด์ง๋ค. ํ์ฌ ์์ฒญ์ ์ ์งํ๊ณ ํ๋์
๋ง์ง ์๋ ์ค๋๋ ๋ฌธ๋งฅ๋ถํฐ ์๋ตํ๋ค. ๋ณ๋ ์ฅ๊ธฐ transcript๋ ์ ์ฅํ์ง ์์ง๋ง ๋ค์ Run์ ์ ๋ฌํ ๋ฌธ๋งฅ์
๊ทธ Run์ goal์ ํฌํจ๋๋ค. /clear๋ ๋ฌธ๋งฅ๊ณผ active/last pointer๋ง ์ ๊ฑฐํ๋ฉฐ SQLite Run์ ์ญ์ ํ์ง ์๋๋ค.
๊ฐ์ ์ธ์
์์๋ /resume์ผ๋ก ํ์ฌ/๋ง์ง๋ง Run์ ์ฌ๊ฐํ๋ค. ๋ค๋ฅธ process์์ ์ฌ๊ฐํ๋ ค๋ฉด /status์
Run ID๋ฅผ ๊ธฐ๋กํ๋ค. --debug ๋๋ pipe ๋ชจ๋์์๋ stderr์ XGEN_STARTED run_id=...๋ ์ฌ์ฉํ ์ ์๋ค.
xgen> /resume run-0123456789abcdef0123456789abcdef
์์ ์๋ฃ์ ๋ํ ์๋ต์ ์ ์ฅํ Run์ model, workspace ๋๋ tool effect ์์ด summary๋ฅผ offline replayํ๋ค. Approval ๋๊ธฐ Run์ ๋์ผํ physical workspace์ ์๋ catalog snapshot์ด ํ์ํ๋ค. ๋๊ตฌ binary, PATH ๋๋ safe environment๊ฐ ๋ฐ๋์ด execution profile์ด ๋ฌ๋ผ์ง๋ฉด configuration mismatch๋ก fail-closedํ ์ ์๋ค.
์ผ๋ฐ TTY ํ๋ฉด์ ์์ฒญ ์ฒ๋ฆฌ ์ค Thinkingโฆ๊ณผ ๊ฒฝ๊ณผ ์๊ฐ์ ํ์ํ๋ค. ์ด ํ์๋ model ํธ์ถ๋ฟ ์๋๋ผ
๋๊ตฌ ์คํ๊ณผ ๊ฒฐ๊ณผ ๊ฒ์ฆ ์๊ฐ์ ํฌํจํ๋ฉฐ, model์ ๋ด๋ถ reasoning text๋ฅผ ๋ปํ์ง ์๋๋ค. ์น์ธ ์
๋ ฅ์ด๋
๊ฒฐ๊ณผ ์ถ๋ ฅ ์ ์ ํ์๋ฅผ ์ง์ด๋ค. ์ต์ข
summary๋ง durable completion ๊ฒ์ฆ ๋ค control character๋ฅผ escapeํด
์ถ๋ ฅํ๋ฉฐ, Run ID๋ /status์์ ํ์ธํ ์ ์๋ค. ์ด ๊ฒ์ฆ์ Receipt์ ๊ฒฐ๊ณผ ์ ์ฅ์ ๊ฒฐํฉยท๋ฌด๊ฒฐ์ฑ์
ํ์ธํ๋ฉฐ, summary์ ๋ชจ๋ ์์ฐ์ด ์ค๋ช
์ด ์ค์ ๋ณ๊ฒฝ๊ณผ ์ผ์นํจ์ ๋ณด์ฅํ์ง ์๋๋ค.
# ๊ธฐ์กด durable progress์ Run ID ๋ก๊ทธ ํ์ธ
xgen --debug--debug์ pipe ์
๋ ฅ์์๋ ๊ธฐ์กด progress: event ๋ฐ XGEN_STARTED ๊ณ์ฝ์ ์ ์งํ๊ณ ANSI animation์
์ถ๋ ฅํ์ง ์๋๋ค. Progress๋ runtime์ redacted lifecycle event์ด๋ฉฐ strict JSON proposal์ ํ์ํ์ง ์๋๋ค.
--debug๋ run๊ณผ resume์๋ ๊ฐ์ progress: event๋ฅผ ๊ฐ์ formatter๋ก ๋ด๋ณด๋ธ๋ค. ์ ๋ถ stderr์
๊ธฐ์กด XGEN_* ๊ฒฐ๊ณผ ์ค ์์ ์ฐ๋ฏ๋ก stdout์ ์ต์ข
์๋ต๋ง ๋ด๋๋ค. ํ๋๊ทธ๋ฅผ ์ฃผ์ง ์์ผ๋ฉด ์๋ฌด event๋
๋ด๋ณด๋ด์ง ์์์, ๊ฒฐ๊ณผ ์ค๋ง ํ์ฑํ๋ host๋ ๋ฌป์ง ์์ prefix๋ฅผ ๋ฐ์ง ์๋๋ค. ์งํ ํ์ ์ฐ๊ธฐ๊ฐ ์คํจํด๋
Run์ ๊ณ์ํ๋ค. ์ง๋จ ํ ์ค์ ์์ ๊ฒ์ด ์ด๋ฏธ ์งํ ์ค์ธ durable ์์
์ ๋ฒ๋ฆด ์ด์ ๋ ์๋๊ณ , run์
์ค๋จ์ process-level signal handler๊ฐ ์์ ํ๋ค.
Ctrl+C๋ ๋ค์ ์์ ํ durable ๊ฒฝ๊ณ์์ ๋ฉ์ถ๋ค. Model request๋ process outcome์ด ์ด๋ฏธ ๋ถํ์ ํด์ก์ผ๋ฉด
user_cancelled๋ณด๋ค model_call_unknown/effect_outcome_unknown์ด ์ฐ์ ํ๊ณ ์๋ ์ฌ์คํํ์ง ์๋๋ค.
Network/process call์ด ์งํ ์ค์ด๋ฉด configured timeout๊น์ง ๊ธฐ๋ค๋ฆด ์ ์๋ค.
์ผ๋ฐ TUI๋ ์๋ฃ๋ ๋ต๋ณ๊ณผ Changes๋ฅผ ๊ฒฐ๊ณผ ๋ธ๋ก์ผ๋ก ๋ณด๊ดํ๋ค. ๋ฐ์ ์์ ์ ์ฐฝ ํญ์ผ๋ก 12ํ์ ๋์ผ๋ฉด
์ 4ํ๊ณผ ๋ค 2ํ๋ง ํ์ํ๊ณ Ctrl+O ์๋ด๋ฅผ ๋ฃ๋๋ค. ํ ์ค์ง๋ฆฌ ๊ธด ๋ฌธ๋จ๋ ํ์ ํญ์ ๊ธฐ์ค์ผ๋ก ์ ๋๋ค.
Ctrl+O: ์ต๊ทผ ๊ฒฐ๊ณผ ์ ์ฒด ๋ณด๊ธฐ. ๋ฐฉํฅํค ์ยท์๋,PgUpยทPgDnยทSpace, HomeยทEnd๋ก ์ด๋ํ๋ค.- ๋ฐฉํฅํค ์ขยท์ฐ: ๋ณด๊ด๋ ๋ค๋ฅธ ๋ต๋ณยท๋ณ๊ฒฝ ๋ด์ญ์ผ๋ก ์ด๋ํ๋ค.
Esc,q,Ctrl+O,Ctrl+C,Ctrl+D: ์ ์ฒด ๋ณด๊ธฐ๋ฅผ ๋ซ๊ณ ์ ๋ ฅ์ฐฝ์ผ๋ก ๋์๊ฐ๋ค. ์ ์ฒด ๋ณด๊ธฐ์์Ctrl+C๋ Run์ ์ทจ์ํ์ง ์๋๋ค. ๋์์จ ๋คCtrl+C๋ฅผ ๋๋ฅด๋ฉด ๊ธฐ์กด ์ทจ์ ๋์์ ํ๋ค.
์ ์ฒด ๋ณด๊ธฐ๋ ์ฝ๊ธฐ ์ ์ฉ์ด๋ค. Enter๋ ๋ถ์ฌ๋ฃ๊ธฐ๋ก ๋ชฉํ๋ฅผ ๋ณด๋ด๊ฑฐ๋ ์น์ธํ์ง ์๋๋ค. ์ด๊ธฐ ์ ์ ์
๋ ฅ๊ณผ ๋๊ธฐ์ด์
์ ์งํ๊ณ , Run์ด ๊ณ์ ์งํ๋ผ ์น์ธ์ด๋ ์ ๊ฒฐ๊ณผ๊ฐ ๋์ฐฉํ๋ฉด ์๋์ชฝ์ ์๋ดํ๋ค. Esc๋ก ๋์์ค๋ฉด ์น์ธ prompt์
์ ์ถ๋ ฅ์ด ๋ํ๋๋ค. ์ ์ฒด ๋ณด๊ธฐ์๋ง ์์ alternate screen์ ์ฌ์ฉํ๊ณ , ๋ซ์ผ๋ฉด ๊ธฐ์กด terminal scrollback์ผ๋ก ๋์์จ๋ค.
TUI ๋ณ๊ฒฝ ๋ด์ญ์ ํ์ผ๋น 12์คยท์ ์ฒด 40์ค๋ก ์๋ฆฐ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ๋์ ์ ์ฒด rendered ๋ด์ฉ์ ๋ณด๊ดํ๋ฏ๋ก, ์ ์ฒด ๋ณด๊ธฐ์์ ๊ทธ ๋ค์ editยท์ ํ์ผยท๊ต์ฒด ํ์ผ ๋ด์ฉ๊ณผ ์คํ ๋ช ๋ น ์ธ์๋ ์ฝ์ ์ ์๋ค. ์๋ฌธ์ ํ๋ฉด ์ถ๋ ฅ์ฉ escape๋ฅผ ๊ฑฐ์น ๋ด์ฉ์ด๋ค.
์บ์๋ ์ต๊ทผ 20๊ฐ ๊ฒฐ๊ณผ ๋ธ๋ก, ์๋ฌธยทํ ๋ฐฐ์ด ํฉ๊ณ 8 MiB๊น์ง๋ค. ์ค๋๋ ํญ๋ชฉ์ ์ ์ฒด ๋ณด๊ธฐ ๋ชฉ๋ก์์ ๋น ์ง์ง๋ง durable Run ๊ธฐ๋ก์ ์ญ์ ํ์ง ์๋๋ค. ํ ๋ธ๋ก์ด ํ๋๋ณด๋ค ํฌ๋ฉด ์ ์ง ์๊ณ ์ ์ฒด๋ฅผ ์ถ๋ ฅํ๋ค. ์ ์ฒด ๋ณด๊ธฐ ์ค ๋ณด๋ฅํ ์ ์ถ๋ ฅ์ด 8 MiB๋ฅผ ๋์ผ๋ฉด ์ ์ฒด ๋ณด๊ธฐ๋ฅผ ๋ซ๊ณ ์ถ๋ ฅํด ๋ด์ฉ์ ์์ง ์๋๋ค.
--debug, pipe ์
๋ ฅ, headless runยทresume์ ์ ์ง ์๋๋ค. ํค์ ๊ฒฝ๊ณ๋ ADR-0078์ ๋ฐ๋ฅธ๋ค.
Pipe ์ ๋ ฅ์์๋ first-run hidden prompt๋ฅผ ์๋์ผ๋ก ์ด์ง ์๋๋ค. Profile์ด๋ ํ๊ฒฝ๋ณ์๋ฅผ ๋จผ์ ๊ณต๊ธํ๋ฉด ๊ฒฐ์ ์ smoke script๋ฅผ ์คํํ ์ ์๋ค. Secret์ script text๋ argv์ ๋ฃ์ง ์๋๋ค.
printf '/status\n/exit\n' | xgen์ค์ goal์ pipe๋ก ์คํํ ๋ ์๊ฒฉ HTTPS credential์ XGEN_OPENAI_API_KEY ๊ฐ์ ์ธ๋ถ secret injection์
์ฌ์ฉํ๋ค. ์ผ๋ฐ ์๋ํ๋ exit code์ ๊ณ ์ stderr ๊ณ์ฝ์ด ๋ ๋จ์ํ ๊ธฐ์กด xgen run/resume์ ๊ถ์ฅํ๋ค.
๋ํ ์๋ต์ ์ ์ฅยท๊ฒ์ฆ ๊ณ์ฝ์ ADR-0047์ ๋ฐ๋ฅธ๋ค.
Unix์์ error: state_directory_permissions๊ฐ ๋์ค๋ฉด ํจ๊ป ํ์๋ state_directory์
permissions๋ฅผ ํ์ธํ๋ค. ํด๋น ํด๋์ group/other ์ ๊ทผ์ ์ ๊ฑฐํด์ผ ํ๋ค.
ํ์ธํ ๊ฒฝ๋ก์ chmod go-rwx -- PATH๋ฅผ ์ง์ ์คํํ๋ฉด ์์ ์ ๊ถํ์ ์ ์ง๋๋ค.
ํ๋ก๊ทธ๋จ์ ๊ถํ์ ์๋ ๋ณ๊ฒฝํ๊ฑฐ๋ ์ฌ๊ท์ ์ผ๋ก ๊ณ ์น์ง ์๋๋ค. ๊ฒฝ๋ก๋ ์ ์ด ๋ฌธ์๋ฅผ escapeํ ์ธ์ฉ ํ๊ธฐ๋ค.
headless runยทresumeยทusageยทrecover๋ ๊ฐ์ code์ ์ง๋จ์ stderr์ ๋ด๋ณด๋ด๊ณ exit 64๋ก ๋๋๋ค.
symlink๋ ์ผ๋ฐ I/O ์คํจ์๋ ์ด ๋ณต๊ตฌ ์๋ด๋ฅผ ๋ถ์ด์ง ์๋๋ค. ์์ธํ ๋ฒ์๋
ADR-0080์ ๋ฐ๋ฅธ๋ค.