injaneity/pi-computer-use 딥다이브
— AI 에이전트에게 눈과 손을 달아주기

1프로젝트 한줄 요약

pi-computer-use의 정체성은 "Pi의 확장"이라는 데 있다. Pi는 @earendil-works/pi-coding-agent라는 이름의 코딩 에이전트 런타임인데, pi-computer-use는 여기에 pi.registerTool(...)로 컴퓨터 유즈 도구 11개를 등록한다. 즉 이 저장소 자체는 "에이전트"가 아니라 "에이전트에게 손발을 붙이는 부품"이다. 덕분에 프로젝트 범위가 명확하다 — 모델을 만들거나 프롬프트를 설계하는 게 아니라, 관측·행동·검증이라는 세 동작을 얼마나 정확하고 안전하게 제공하느냐에만 집중한다.

2왜 주목받는가

컴퓨터 유즈 도구는 이미 여럿 있다. 대부분은 스크린샷을 찍어 모델에게 이미지로 주고, 모델이 "여기 클릭"이라고 좌표를 뱉으면 그 좌표를 클릭하는 방식이다. 단순하지만 약점이 크다 — 화질·배율·폰트에 따라 좌표가 흔들리고, 클릭이 실제로 먹혔는지 확인할 방법이 없다. pi-computer-use는 이 두 약점을 정면으로 겨냥한다.

2-1. 접근성 트리 우선, 픽셀은 최후의 수단

2-2. "먹혔다고 우기지 않는" 정직한 결과

이 프로젝트가 진짜 공들인 지점이다. act_ui는 동작을 보낸 뒤 결과를 worked(먹힘) / didnt(안 먹힘) / unknown(모름) 세 가지로 정직하게 보고한다. "이벤트를 보냈다"는 사실만으로는 성공이라고 절대 치지 않는다. 버튼을 눌렀는데 앱이 그 이벤트를 씹었을 수도 있으니, 원하면 expect로 "누른 뒤 '저장됨'이라는 글자가 뜰 것"이라는 사후조건(postcondition)을 붙일 수 있고, 그게 확인돼야만 성공 처리된다.

2-3. 두 OS를 "같은 규칙"으로 묶은 설계

macOS는 Swift로 AX(Accessibility)와 ScreenCaptureKit를, Windows는 Rust로 UIA(UI Automation)를 쓴다. 내부 구현은 완전히 다르지만, 이 저장소는 두 헬퍼가 똑같은 불변식(invariant) 집합을 지키도록 강제한다. 헬퍼는 시작할 때 자기가 구현한 불변식 목록과 architectureVersion을 보고하고, 필수 불변식이 빠지면 기동 자체가 실패(fail closed)한다. "OS별로 동작이 미묘하게 다른" 흔한 함정을 구조로 막은 것이다.

또 하나 눈에 띄는 건 테스트·검증 스크립트의 밀도다. scripts/ 폴더에 스키마 검사, 세션 생명주기 검사, 런타임 동시성 검사, 출력 상한 검사, 커밋 메시지 검사, 서명 검사까지 10여 개의 자체 검증 러너가 있고, pi-cubench-agent.mjs라는 벤치마크(Cubench)로 두 OS에서 같은 블랙박스 속성을 돌린다. 별 137개짜리 신생 프로젝트치고 엔지니어링 규율이 상당히 촘촘하다는 신호다.

3기술 스택 전체 지도

3-1. 브리지 계층 (TypeScript, src/)

에이전트와 네이티브 헬퍼 사이를 잇는 두뇌다. 모델의 의도를 해석하고, 상태를 저장·복원하고, 자원 스케줄링을 담당한다. 실제 그라운딩(어디를 누를지 확정)과 입력 전달은 네이티브 헬퍼에 맡긴다.

3-2. macOS 네이티브 헬퍼 (Swift, native/macos/)

핵심은 bridge.swift 3,544줄 단일 파일이다. AXRefStore(접근성 요소 참조 저장), LookNode(관측 트리 노드), Bridge(소켓 서버 본체), InputSuppressionGuard(입력 억제 가드)가 들어 있다. 화면 캡처는 ScreenCaptureKit, UI 구조는 AX(Accessibility) API, 유령 커서 오버레이는 AppKit으로 그린다(agent_cursor.swift, agent_cursor_motion.swift). 소켓 서버는 메인 스레드 밖에서 돌고, AppKit이 메인 런루프를 소유한다.

3-3. Windows 네이티브 헬퍼 (Rust, native/windows/bridge-rs/)

Windows 헬퍼는 macOS의 TCC 권한 흐름이나 헬퍼 앱을 쓰지 않고, 대화형 데스크톱 세션에서 UIA로 바로 동작한다. 고정 크기 워커 풀을 쓰고 각 워커 스레드마다 UIA를 초기화하며, 물리 입력이 필요한 배치만 전역 입력 락을 잡는다.

3-4. 언어·의존성 요약

4아키텍처 심화 분석

이 장이 문서의 심장이다. pi-computer-use의 아키텍처는 한 문장으로 요약된다 — "루트를 찾고 → 한 루트를 관측하고 → 그 관측 상태 안에서 검색/펼침/조사하고 → 그 상태로부터 행동한다." 여기서 반복해서 등장하는 세 가지 참조를 먼저 익히면 나머지가 쉽다.

4-1. 전체 흐름 — 요청 하나의 생애

4-2. 핵심 설계 패턴 ① — 불변 상태 + 에포크로 stale-write 막기

가장 독창적인 부분이다. 일반적인 자동화 도구는 "현재 화면"이라는 가변(mutable) 전역 상태를 두고 매번 갱신한다. 그런데 Pi는 도구 호출을 동시에(concurrently) 날릴 수 있다. 이러면 A 호출이 화면을 바꾸는 사이 B 호출이 옛 화면 기준으로 클릭해 버리는 경합(race)이 생긴다.

pi-computer-use의 해법은 "현재 화면을 아무도 공유하지 않는다"이다. 관측 결과는 전부 불변(immutable)으로 저장되고, 각 물리 자원(프로세스·CDP 타깃)에는 단조 증가하는 에포크(epoch)가 붙는다. 화면을 바꾸는 호출은 자기 상태가 캡처한 에포크를 반드시 제시해야 하고, 그 사이 다른 쓰기가 이겼으면 오래된 호출은 전송 전에 stale 에러로 거부된다.

4-3. 핵심 설계 패턴 ② — 자원별 스케줄링(전체가 아니라 자원 단위로 직렬화)

동시성을 무조건 막으면 느리다. pi-computer-use는 같은 물리 자원을 건드리는 라이브 동작만 순서대로 처리하고, 서로 다른 자원은 병렬로 흘려보낸다.

4-4. 핵심 설계 패턴 ③ — 점진적 공개(progressive disclosure)

큰 앱의 접근성 트리는 수천 개 노드로 폭발한다. 이걸 통째로 모델에게 주면 토큰이 낭비되고 정확도도 떨어진다. 그래서 observe_ui는 처음에 접힌(folded) 요약뷰만 준다. 세부는 필요할 때만 캐시된 완전한 트리에서 꺼낸다.

// 1) 처음엔 컴팩트한 관측
observe_ui({ root: "@r1" })

// 2) 캡처를 새로 하지 않고 저장된 상태만 질의
search_ui({ stateId, text: "저장" })       // 텍스트/역할/능력으로 랭킹 검색
expand_ui({ stateId, ref: "@e7", depth: 3 }) // 한 요소 주변만 펼침
inspect_ui({ stateId, ref: "@e12" })         // 필드·좌표·능력·증거 자세히

관측 모드는 3단계다 — semantic(접근성만, 가장 쌈), fused(기본, 자동 선택), visual(이미지·OCR 강제). 검색은 정확→접두→부분 일치를 보수적 퍼지 매치보다 우선해 랭킹하고, 고정된 상위 집합 + 총 매치 수를 돌려주며, 검색이 너무 넓으면 "좁혀서 다시 검색하라"고 요구한다(매치를 페이지 넘김하며 훑지 않는다).

4-5. 핵심 설계 패턴 ④ — 행동, 배치, 그리고 정직한 결과

act_ui는 의존적인 동작 목록 하나를 받는다. 배열 길이가 1이면 단일 동작, 여러 개면 한 트랜잭션이다. 단, 배치는 "중간 관측이 필요 없을 때만" 허용된다 — 두 번째 동작이 첫 번째의 결과를 봐야 한다면 한 개씩 보내고 관측해야 한다.

// 편집 영역 클릭 → 그 포커스로 타이핑 (ref 생략 = 방금 만든 포커스에 입력)
act_ui({
  stateId,
  actions: [
    { action: "click", x: 420, y: 300 },
    { action: "typeText", text: "hello" },
  ],
  expect: { text: "hello" },   // 이 글자가 떠야 성공
})

여기에 headless 플래그가 두 세계를 가른다. headless: true면 배경 경계가 엄격하다 — 앱을 앞으로 띄우지도, 사용자 포커스 창을 바꾸지도, 전역 커서를 움직이지도, 날 입력을 쏘지도 않는다. headless: false(기본)면 배경에서 의미론적 활성화를 시도하고, 검증에 실패한 부작용 없는 키보드 입력은 전경(foreground)으로 자동 승격해 재시도한다. 단 애매한 포인터 동작은 절대 맹목적으로 재시도하지 않는다(같은 클릭을 두 번 하면 두 번 눌릴 위험).

4-6. 후속 diff — "바뀐 것만" 보여주기

동작이 끝나면 화면 전체를 다시 주는 건 낭비다. view.ts는 동작 후 상태를 이전 상태와 비교해 신뢰할 수 있는 변경분(added/updated/removed)만 렌더링하고 다음 stateId를 준다. 요소가 확실히 매칭되면 모델이 쓰던 @e 참조를 그대로 유지한다.

단, 루트 자체가 바뀌었거나(창이 통째로 교체) 매칭 신뢰도가 낮거나 변경분이 너무 많으면 접힌 전체뷰로 폴백한다. 어느 경우든 search_ui 등 캐시 질의는 언제나 저장된 완전한 상태를 본다 — 부분 적용된 모델측 트리가 아니라.

4-7. 브라우저 지원 — 페이지도 그냥 하나의 루트다

브라우저 페이지는 별도의 "두 번째 세계"가 아니라 포레스트의 또 다른 @r 루트다. launch_browser가 관리형 CDP 브라우저를 띄워 페이지 상태를 돌려주면, observe_ui·act_ui·read_text·wait_for가 데스크톱과 똑같이 동작한다. CDP 접근성 트리를 데스크톱과 동일한 아웃라인 모양으로 변환하기 때문이다. navigate_browser·evaluate_browser만 CDP 전용이고, 나머지는 계약(contract)이 완전히 공유된다.

4-8. 플랫폼 드리프트 방지 — 소스가 아니라 불변식으로 통일

4-9. 경계 있는 출력

모델에게 보이는 모든 텍스트 결과는 48KiB 또는 2,000줄로 제한된다. 초과분은 16KiB 미리보기 + 좁히기 안내 + 불변 @o 연속 참조를 준다. read_text({ ref: "@o1", offset })로 이어 읽되, @o 오프셋은 UTF-8 바이트 단위, @e 텍스트 오프셋은 유니코드 문자 단위라는 미묘한 차이가 있다.

5디렉토리 구조 해부

6학습 포인트

6-1. 실제 코드 발췌

도구 등록 (extensions/computer-use.ts)

export default function computerUseExtension(pi: ExtensionAPI): void {
  for (const tool of [findTool, observeTool, searchUiTool, expandUiTool,
                     inspectUiTool, actTool, readTextTool, waitForTool,
                     launchBrowserTool, navigateBrowserTool, evaluateBrowserTool])
    pi.registerTool(tool);

  pi.on("session_start", async (_e, ctx) => {
    loadComputerUseConfig(ctx.cwd);
    reconstructStateFromBranch(ctx);          // 이전 대화 분기에서 상태 복원
    if (ctx.hasUI) await ensureComputerUseSetup(ctx); // 권한 셋업 안내
  });
}

동작 스키마 — 참조 클릭 vs 좌표 클릭 (typebox 유니온)

const clickByRef   = Type.Object({ action: Type.Literal("click"), ref: Type.String(), … });
const clickByPoint = Type.Object({ action: Type.Literal("click"), x: Type.Number(), y: Type.Number(), … });
const uiAction = Type.Union([
  Type.Object({ action: Type.Literal("press"),   ref: Type.String() }),
  clickByRef, clickByPoint,
  Type.Object({ action: Type.Literal("setText"), ref: Type.String(), text: Type.String() }),
  Type.Object({ action: Type.Literal("typeText"),ref: Type.Optional(Type.String()), text: Type.String() }),
  // keypress, scroll, drag, moveMouse …
]);

사후조건이 붙는 검증형 행동 (docs/usage.md)

act_ui({
  stateId,
  actions: [{ action: "press", ref: "@e12" }],
  expect: { text: "Archive completed", until: "present", timeoutMs: 3000 }
})
// 결과: verified(새로 확인) / preexisting(이미 그랬음) / failed
// 앱이 이벤트를 씹으면 → didnt + postcondition_failed

설정 우선순위 — 기본값 < 파일 < 환경변수 (src/config.ts)

const DEFAULT_CONFIG = { browser_use: true, headless: false,
                        cursor_overlay: true, managed_browser: "chrome" };
// ~/.pi/.../pi-computer-use.json → cwd/.pi/computer-use.json → PI_COMPUTER_USE_* env
for (const source of sources) if (source.values) Object.assign(config, source.values);
Object.assign(config, env); // env가 최종 승자

6-2. 이 저장소에서 배울 수 있는 기술

7시스템 요구사항

설치

# npm 배포판
pi install npm:@injaneity/pi-computer-use

# 또는 GitHub에서 직접 (전역/프로젝트-로컬)
pi install git:github.com/injaneity/pi-computer-use
pi install -l git:github.com/injaneity/pi-computer-use

설정 (선택)

# 환경변수로 오버라이드 (파일 설정보다 우선)
export PI_COMPUTER_USE_HEADLESS=true         # 배경 전용, 사용자 포커스 안 건드림
export PI_COMPUTER_USE_CURSOR_OVERLAY=false  # 유령 커서 끄기
export PI_COMPUTER_USE_MANAGED_BROWSER=helium

# Pi 안에서 현재 설정 확인
/computer-use

8직접 해볼 수 있는 실습 과제

9심화 학습 로드맵

10핵심 키워드 사전

11참고 링크