Cupcake

AI 에이전트가 규칙을 따르게 하세요.

AI 에이전트를 위한 정책 적용(Policy enforcement) 계층으로, 모델 컨텍스트를 소모하지 않으면서 더 나은 성능과 보안을 제공합니다.

• 에이전트를 위한 결정적 규칙 준수. 대화형 예제
• 규칙을 컨텍스트 밖으로 옮기고 정책-코드(policy-as-code)로 전환하여 더 나은 성능을 제공합니다.
• 경고 트리거 및 규칙을 반복적으로 위반하는 잘못된 에이전트를 타임아웃 처리합니다.

Cupcake는 에이전트 이벤트를 가로채서 사용자 정의 규칙을 기준으로 평가하며, 이 규칙은 Open Policy Agent (OPA) Rego로 작성됩니다. 에이전트 작업은 에이전트에게 유용한 피드백을 제공함으로써 차단, 수정, 자동 수정될 수 있습니다. 추가적인 이점으로는 에이전트에 의존할 필요가 없는 작업(예: 파일 편집 후 린팅)을 위한 반응형 자동화가 있습니다.

업데이트

2025-12-10: 공식 오픈소스 릴리스. 로드맵은 2026년 1분기에 제공될 예정입니다.

2025-04-04: Claude Code Hooks에 대한 기능 요청을 제출했습니다. 런타임 정렬을 위해서는 에이전트 하네스에 대한 통합이 필요하며, 에이전트 동작의 파일시스템 및 OS 수준 모니터링(초기 cupcake PoC)에서 방향을 전환했습니다.

지원되는 에이전트 하네스

Cupcake는 여러 AI 코딩 에이전트를 위한 경량 네이티브 통합을 제공합니다:

각 하네스는 네이티브 이벤트 형식을 사용합니다. terraform과 유사하게 정책은 하네스별로 구분됩니다(policies/claude/, policies/cursor/, policies/factory/, policies/opencode/). 이는 명확성을 보장하고 하네스별 기능에 완전히 접근할 수 있게 하기 위함입니다. 특정 하네스가 지원되지 않는 경우, 런타임 통합 수단이 없기 때문입니다.

언어 바인딩

Cupcake는 네이티브 바인딩을 통해 JavaScript 에이전트 애플리케이션에 내장될 수 있습니다. 이를 통해 LangChain, Google ADK, NVIDIA NIM, Vercel AI SDK 등과 같은 웹 기반 에이전트 프레임워크와의 통합이 가능합니다.

언어	바인딩
TypeScript	./cupcake-ts

작동 원리

Cupcake는 코딩 에이전트와 런타임 환경 사이에서 에이전트 작업 경로에 직접 연결되는 후크를 통해 적용 계층으로 작동합니다.

Agent → (proposed action) → Cupcake → (policy decision) → Agent runtime

1. 가로채기(Interception): 에이전트가 작업/도구 호출(예: git push, fs_write)을 실행하려고 준비합니다.
2. 보강(Enrichment): Cupcake는 현재 Git 브랜치, CI 상태, 데이터베이스 메타데이터 등 환경의 사실인 실시간 **신호(Signals)**를 수집합니다.
3. 평가(Evaluation): 작업과 신호는 JSON 입력으로 패키징되어 밀리초 단위로 Wasm 정책에 대해 평가됩니다.

결정적 및 비결정적 평가

Cupcake는 두 가지 평가 모델을 지원합니다:

1. 결정적 정책(Deterministic Policies): 정책은 OPA/Rego로 작성되며 빠르고 샌드박스된 평가를 위해 WebAssembly(Wasm)로 컴파일됩니다. 구현 세부 사항은 정책 작성 가이드를 참조하세요.
2. LLM‑as‑Judge: 보다 간단하면서도 더욱 고급스러운 규칙 감독을 위해, Cupake는 보조 LLM 또는 에이전트를 통해 개입하여 작업이 어떻게 진행되어야 하는지 평가할 수 있습니다. 구현 세부 사항은 Cupcake Watchdog 가이드를 참조하세요.

결정 및 피드백

평가에 따라 Cupcake는 사람이 읽을 수 있는 메시지와 함께 다섯 가지 결정 중 하나를 에이전트 런타임에 반환합니다:

• Allow(허용): 작업이 진행됩니다. 선택적으로 Cupcake는 차단 없이 후속 동작을 안내하기 위해 Context(컨텍스트)(예: "기억하세요: 현재 main 브랜치에 있습니다")를 주입할 수 있습니다. 참고: Context 주입은 Claude Code 및 Factory AI에서 지원되며 Cursor에서는 지원되지 않습니다.
• Modify(수정): 변환된 입력으로 작업이 진행됩니다. 정책은 명령을 정화(sanitize)하거나 안전 플래그를 추가하거나 실행 전에 규칙을 강제할 수 있습니다. 참고: Claude Code 및 Factory AI에서만 지원됩니다.
• Block(차단): 작업이 중지됩니다. Cupcake는 차단된 _이유_를 설명하는 **Feedback(피드백)**을 보내 에이전트가 스스로 수정할 수 있게 합니다(예: "푸시하기 전에 테스트가 통과해야 합니다").
• Warn(경고): 작업은 진행되지만, 경고가 기록되거나 표시됩니다.
• Require Review(검토 필요): 사람이 승인할 때까지 작업이 일시 중지됩니다.

왜 Cupcake인가?

최신 에이전트는 강력하지만, 특히 컨텍스트가 커질수록 운영 및 보안 규칙을 따르는 데 일관성이 없습니다. Cupcake는 이미 관리 중인 규칙(예: CLAUDE.md, AGENT.md, .cursor/rules)을 작업 실행 전에 작동하는 실행 가능한 가드레일로 전환합니다.

• 다중 하네스 지원(Multi-harness support): Claude Code, Cursor, Factory AI, OpenCode에 대한 일급 통합을 제공합니다.
• Governance‑as‑code(거버넌스-코드): 빠르고 샌드박스된 평가를 위해 WebAssembly로 컴파일된 OPA/Rego를 사용합니다.
• Enterprise‑ready(엔터프라이즈 지원): 허용/거부/검토 컨트롤, AI SOC를 위한 향상된 감사(Enriched audit) 추적, 사전 경고를 제공합니다.

핵심 기능

• 세밀한 도구 제어(Granular Tool Control): 특정 도구나 인수를 차단합니다(예: rm -rf / 차단).
• MCP 지원(MCP Support): Model Context Protocol 도구(예: mcp__memory__*, mcp__github__*)에 대한 네이티브 거버넌스를 제공합니다.
• LLM‑as‑Judge: 보다 동적인 감독을 위해 보조 LLM 또는 에이전트를 사용하여 작업을 평가합니다.
• 가드레일 라이브러리(Guardrail Libraries): 콘텐츠 및 안전 검사를 위해 NeMo 및 Invariant와의 일급 통합을 제공합니다.
• 관찰 가능성(Observability): 모든 입력, 신호, 결정은 디버깅을 위해 구조화된 로그와 평가 트레이스를 생성합니다.

Nix를 사용한 설치 및 개발

nix를 사용하고 있다면, 제공된 flake를 사용하여 Cupcake를 설치하고 실행할 수 있습니다:

Nix를 사용하여 Cupcake CLI 설치

# Install directly from GitHub
nix profile install github:eqtylab/cupcake#cupcake-cli

# Or run without installing
nix run github:eqtylab/cupcake#cupcake-cli -- --help

NixOS에 Cupcake CLI 설치

다음을 flake.nix에 추가하세요:

inputs.cupcake.url = "github:eqtylab/cupcake";

그런 다음 environment.systemPackages 또는 home.packages에 다음 패키지를 추가하세요:

inputs.cupcake.packages.${system}.cupcake-cli

개발 셸

개발을 위해 Rust 툴체인, just 및 기타 종속성이 포함된 제공된 개발 셸을 사용할 수도 있습니다:

# Enter the development shell
nix develop

FAQ

Cupcake가 프롬프트/컨텍스트 토큰을 소모하나요? 아니요. 정책은 모델 외부에서 실행되며 구조화된 결정을 반환합니다.

Cupcake가 특정 모델에 종속되나요? 아니요. Cupcake는 하네스별 통합을 통해 여러 AI 코딩 에이전트를 지원합니다.

평가 속도는 얼마나 빠른가요? 일반적인 설정에서 캐시된 정책은 1밀리초 미만입니다.

기여

기여를 환영합니다! 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

Apache 2.0

Cupcake는 EQTYLab에서 개발했으며, Trail of Bits의 에이전틱 안전 연구 지원을 받았습니다.

X에서 팔로우하여 정기 업데이트를 받아보세요.