unicity-astrid/sdk-js 딥다이브
— Rust 말고 TypeScript로 AI 에이전트 OS의 '캡슐'을 짜는 SDK

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

sdk-js = "AI 에이전트 OS의 확장 모듈(캡슐)을, 웹 개발자에게 익숙한 TypeScript로 짜게 해 주는 키트." 배경부터 보자. Astrid OS는 "AI 에이전트를 위한 운영체제"다. 그 안에서 도는 모든 프로그램을 캡슐(capsule)이라 부르는데, 캡슐은 샌드박스(WebAssembly) 안에 갇혀, 허락받은 권한과 정해진 자원 한도 안에서만 도는 격리된 프로세스다. 원래 이 캡슐은 Rust로만 짤 수 있었다(sdk-rust). 이 저장소 sdk-js는 바로 그 JavaScript/TypeScript 판 동반 SDK다.

README가 스스로를 이렇게 정의한다 — "같은 WIT 계약, 같은 wasip2 컴포넌트 출력, 같은 .capsule 묶음 포맷 — 그래서 커널은 이 바이너리를 어떤 언어로 만들었는지 알 수 없다." 그리고 사용 감각을 이렇게 비교한다: "Rust SDK가 std를 상대로 코딩하는 느낌이라면, 이 SDK는 node:fs/promises · WHATWG · Node의 EventEmitter를 상대로 코딩하는 느낌이다. 호스트 ABI는 똑같고, 관용구만 번역했다."

정리하면 이 SDK의 핵심 약속은 셋이다. ① 웹 개발자도 에이전트 OS를 확장할 수 있다 — Rust를 몰라도 캡슐을 짠다. ② 결과물은 Rust 캡슐과 100% 호환되는 .capsule 파일이라, 커널·다른 캡슐과 그대로 맞물린다. ③ 코드는 데코레이터 몇 개(@capsule · @tool · @interceptor)와 익숙한 fs/http/kv API로 짜고, 빌드는 ComponentizeJS가 알아서 WASM 컴포넌트로 바꿔 준다. 대신 치러야 할 값(바이너리 크기 ~11MB)도 분명한데, 그건 §2에서 냉정하게 본다.

2왜 주목받는가

TrendShift 월간 16위 — "에이전트 OS 확장을 Rust 독점에서 풀어 준다"는 한 방.

2026년 들어 GitHub 트렌딩은 온통 "에이전트 스킬 · 에이전트 OS" 물결이다(skills 저장소들, hermes-agent, omnigent…). 그 흐름에서 Astrid는 "에이전트를 위한 진짜 운영체제"를 표방하는데, 그 OS를 확장하는 길이 지금까지 Rust 하나뿐이었다. sdk-js는 그 문을 JS/TS 쪽으로 연다. 주목 포인트를 다섯 가지로 본다.

① Rust 장벽을 없앤다 — 가장 큰 개발자 풀에게 문을 연다

캡슐을 짜려면 Rust + 매크로 + WIT를 알아야 했다. 이건 진입장벽이 높다. sdk-js는 똑같은 일을 전 세계에서 가장 인구가 많은 JS/TS 개발자가 할 수 있게 만든다. "에이전트 OS의 플러그인 생태계"를 키우려면 결국 사람 수가 관건인데, 이 SDK가 그 수문을 연다.

② 얇은 FFI가 아니라 "네이티브 JS 느낌"으로 번역했다

흔한 접근은 Rust API를 그대로 JS로 노출하는 얇은 바인딩(FFI)이다 — 어색하고 Rust 냄새가 난다. sdk-js는 반대로 갔다. 파일은 node:fs/promises 모양으로, HTTP는 fetch 폴리필까지, 에러는 Rust의 Result가 아니라 JS답게 throw로. README의 표현대로 "JS와 싸워 가며 Rust 모양 에러를 붙이는 건 '네이티브 느낌'의 정반대"라서다.

③ 같은 호스트 ABI = 언어를 갈아탈 자유

핵심 설계 결정 하나. Rust SDK와 JS SDK는 완전히 동일한 WIT 호스트 ABI를 쓴다. 그래서 자주 호출돼 성능이 중요한 캡슐은 Rust로, 빨리 만들고 싶은 캡슐은 JS로 — 커널을 전혀 바꾸지 않고 캡슐만 언어 이식할 수 있다. "프로토타입은 JS로, 검증되면 Rust로 다시"라는 현실적 전략이 가능해진다.

④ ComponentizeJS + 표준 데코레이터 — 최신 WASM 기술의 실전 사례

이 저장소는 그 자체로 "JS를 진짜 WASM 컴포넌트로 만드는 법"의 교본이다. Bytecode Alliance의 @bytecodealliance/componentize-js(SpiderMonkey 임베드 StarlingMonkey)로 JS를 wasm32-wasip2 컴포넌트로 굽고, TC39 표준 데코레이터(실험 플래그 없는 stage-3)로 Rust의 절차 매크로를 대체한다. 요즘 WASM·TS 생태계의 최첨단이 한 곳에 모여 있다.

⑤ Unicity / Astrid 생태계 — "에이전트가 경제 주체인 인터넷"

배경 서사도 한몫한다. Unicity는 "자율 에이전트의 인터넷(Autonomous Agentic Internet)"을 표방하는 블록체인 플랫폼이고, Astrid OS는 그 위 에이전트 런타임 계층이다. 에이전트를 1급 경제 주체로 두는 큰 그림 안에서, sdk-js는 "그 세계의 앱을 누구나 만들게 하는 입구" 역할로 묶인다.

3기술 스택 전체 지도

루트 package.json(npm workspaces) · 각 패키지의 package.json/tsconfig · 실제 소스 트리에서 확인한 구성.

마음의 준비. 이건 "백엔드+프론트엔드" 웹 앱이 아니라 컴파일 툴체인 + 호스트 바인딩 라이브러리다. 전부 TypeScript(+ 빌드 오케스트레이터는 Node ESM .mjs)이고, npm workspaces로 묶인 모노레포다. 계층은 ⓐ 언어/런타임, ⓑ 빌드 체인, ⓒ 두 패키지, ⓓ 계약·타입, ⓔ 일부러 "안 쓴 것"으로 나뉜다.

ⓐ 언어 · 런타임 — 의외로 엄격하다

ⓑ 빌드 체인 — TS가 WASM 컴포넌트가 되기까지

ⓒ 발행되는 두(+1) 패키지

ⓓ 계약 · 타입 — "제3자 라이브러리가 거의 없다"

특이점: 이 SDK는 외부 crypto·HTTP 라이브러리를 쓰지 않는다. 파일·네트워크·HTTP·난수까지 전부 WIT 호스트 임포트(astrid:*/host@1.0.0)를 거쳐 커널에 부탁한다. 즉 SDK는 디스크나 네트워크를 직접 만지지 않는다 — 보안 샌드박스의 핵심이다. 실제로 임포트하는 호스트 패키지는 11개(fs · net · http · kv · ipc · process · sys · uplink · elicit · approval · identity). 콘텐츠 주소(BLAKE3)·실제 syscall은 전부 Rust 커널 쪽에 있다.

ⓔ 일부러 "안 쓴 것" — 품질은 다르게 지킨다

테스트 러너(vitest/jest)가 없다. npm test는 "나중에 단위테스트가 생기면 채울 자리"라는 빈 껍데기다. 대신 품질을 ① tsc 타입체크(빌드가 곧 전 파일 타입검사), ② CI의 wit-sync --check(아래 §4의 "단일 진실원" 어긋남 감지), ③ 수동 스모크 테스트로 지킨다. docs/ 폴더도 없고, 문서는 각 패키지 README와 notes/phase-*.md 개발 일지가 대신한다.

4아키텍처 심화 분석

먼저 "TS 클래스 한 개가 커널에 설치되기까지" 전체 그림을 본 뒤, 대표 흐름 '도구 호출 한 번'을 끝까지 따라간다.

이 SDK의 일은 두 가지다. (빌드 타임) 내가 쓴 TS 클래스를 wasm32-wasip2 컴포넌트로 굽고, (런타임) 커널이 그 컴포넌트를 부를 때 내 데코레이터 메서드로 정확히 연결해 준다. 부품 이름을 외우기 전에 숲부터 보자.

독수리 시점 — TS 클래스가 커널에 설치되기까지

흐름 ① — "도구 호출 한 번"이 처리되는 전 과정

개발자는 이런 캡슐을 쓴다(예제 test-capsule에서 발췌). 데코레이터가 곧 "이 메서드는 도구다/인터셉터다"라는 표식이다.

// 개발자가 작성하는 캡슐 — 익숙한 클래스 + 데코레이터
import { capsule, tool, interceptor, install, ipc, log } from "@unicity-astrid/sdk";

@capsule
export class TestCapsule {
  counter = 0;

  @tool("increment", { mutable: true })   // 상태를 바꾸는 도구
  increment(_args: object): { counter: number } {
    this.counter = (this.counter + 1) >>> 0;
    log.info(`counter = ${this.counter}`);
    return { counter: this.counter };
  }

  @tool("get_counter")                     // 읽기 전용 도구
  getCounter(_args: object): { counter: number } {
    return { counter: this.counter };
  }

  @interceptor("test.v1.event")            // 특정 IPC 토픽을 가로챔
  handleEvent(_payload: unknown): { handled: boolean } {
    return { handled: true };
  }

  @install onInstall(): void { log.info("installed"); }
}

커널이 increment 도구를 부르면, SDK 안의 브릿지(runtime/bridge.ts)가 아래 순서로 일을 처리한다. 이 디스패치 표가 SDK의 심장이고, Rust의 절차 매크로가 컴파일 타임에 만들어 내던 코드를, 여기선 런타임에 한다.

// 커널이 부르는 단일 진입점(WIT export). action 문자열로 분기
astridHookTrigger(action, payload):

  if action == "tool_describe":
      → 등록된 @tool 들의 스키마 목록을 만들어 반환(캐시)
        각 항목 = { name, description, input_schema }

  if action.startsWith("tool_execute_"):
      req = parse(payload)             // { call_id, tool_name, arguments }
      if 도구가 mutable:  this ← KV의 "__state" 로드   // 상태 복원
      result = await 핸들러(req.arguments)
      if mutable:        KV에 "__state" 저장            // 상태 영속
      ipc.publish("tool.v1.execute.<name>.result", result)
      return { action: "continue" }

  else:
      interceptor / command 맵에서 찾아 실행 → 결과를 그대로 반환

  // 어디서든 에러가 나면 →  return { action: "deny", data: 사유 }

흐름 ② — 데코레이터는 "로드 시점"에 자기를 등록한다

이 모든 디스패치가 가능한 건, 모듈이 로드될 때 데코레이터들이 runtime/registry.ts의 등록부에 자기를 적어 두기 때문이다. @tool("increment")는 "이름 increment → 이 메서드" 매핑을 등록하고, 중복을 즉시 잡는다: 같은 이름 도구를 두 번 선언하거나, @capsule 클래스가 둘이거나, @install이 여럿이면 로드 시점에 에러를 던진다. (클래스 필드가 클래스보다 먼저 평가되는 순서 문제도 WeakMap 버퍼로 처리한다.) 즉 "런타임 등록부 + 동기 정착 브릿지"가 Rust 매크로의 역할을 대신한다.

이 레포에서 배울 핵심 설계 패턴 셋. 첫째, WIT = 단일 진실원 — 호스트 ABI 원본은 별도 저장소 unicity-astrid/wit에 있고, 그걸 contracts 서브모듈로 받아 Rust·JS 양쪽에서 똑같이 코드 생성한다. CI의 wit-sync --check가 "번들된 WIT 미러가 원본과 어긋났는지"를 막아 손편집을 차단한다. 둘째, capability로 잠근 호스트 모듈 — 모든 fs/net 호출은 권한 검사를 거치고 실패 시 SysError를 던진다(Rust는 Result 반환). 셋째, 데코레이터로 매크로를 대체 — 컴파일 타임 코드 생성을 런타임 등록으로 옮긴 영리한 절충.

5디렉토리 구조 해부

npm workspaces 모노레포 · 핵심은 packages/astrid-sdk/src의 22개 TS 모듈. 큰 덩어리만 본다.

복잡성의 대부분은 packages/astrid-sdk/src 안에 모여 있다. 그중 꼭 읽을 두 파일은 runtime/bridge.ts(디스패치 엔진)와 runtime/registry.ts(데코레이터 등록부)다 — §4의 흐름이 전부 여기서 일어난다. 줄 수(LOC)는 "어디가 무겁나"를 가늠하는 힌트다.

6학습 포인트 (기술별)

이 레포 한 채로 배울 수 있는 최신 WASM·TS 기술과, 각각의 실습 아이디어.

sdk-js는 "요즘 가장 뜨거운 WASM·TypeScript 주제"가 한 코드베이스에 모여 있어 공부 소재로 훌륭하다. 기술별로 무엇을 건질지 짚는다.

7하드웨어/시스템 요구사항

GPU 불필요. "Node 20+ 툴체인"이면 빌드는 되지만, 완전히 돌리려면 Rust 커널이 필요하다.

sdk-js는 추론 모델이 아니라 컴파일 도구 + 바인딩 라이브러리라 GPU·고사양이 필요 없다. 다만 주의할 점이 둘 — ① 빌드 산출물 컴포넌트가 ~11MB로 크고, ② 이 저장소만으로는 캡슐을 설치·실행까지 못 한다(Rust 쪽 패킹·커널 필요).

가장 빠른 출발점은 레포를 클론해 npm ci && npm run build로 예제 캡슐을 컴포넌트로 굽는 것이다. 커널 없이도 "TS→WASM 컴포넌트" 변환까지는 눈으로 확인할 수 있다 — 데코레이터·번들·componentize의 한 사이클을 손에 익히기 좋다.

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

"빌드 한 번"은 10분, "내 도구 추가·언어 이식"은 한나절. 난이도 순으로.

9관련 기술 심화 학습 로드맵

sdk-js를 100% 소화하기 위한 6주 코스(주당 5~7시간 가정).

10핵심 키워드 사전

이 문서와 레포에 등장한 용어를 한자리에.

11참고 링크

원문·동반 저장소·관련 기술 더 파기.

• GitHub 저장소(이 글) — github.com/unicity-astrid/sdk-js (README·소스·examples)
• sdk-rust (Rust 원조) — github.com/unicity-astrid/sdk-rust (같은 WIT 계약의 Rust 판)
• astrid (커널) — github.com/unicity-astrid/astrid (캡슐을 실제로 돌리는 OS)
• RFCs / 설계 문서 — github.com/unicity-astrid/rfcs
• Unicity 생태계 — github.com/unicitynetwork (블록체인 플랫폼)
• TrendShift 페이지 — trendshift.io/repositories/50931
• ComponentizeJS — github.com/bytecodealliance/ComponentizeJS (JS → WASM 컴포넌트)
• WASM 컴포넌트 모델 — component-model.bytecodealliance.org · wasi.dev