Cupcake

Fai in modo che gli agenti AI seguano le regole.

Layer di policy enforcement per agenti AI; offre prestazioni e sicurezza migliori senza consumare il contesto del modello.

• Rispetto deterministico delle regole per i tuoi agenti. Esempi interattivi
• Prestazioni migliori spostando le regole fuori dal contesto e nella policy-as-code.
• Attiva avvisi e metti in timeout gli agenti cattivi quando violano ripetutamente le regole.

Cupcake intercetta gli eventi degli agenti e li valuta rispetto a regole definite dall'utente scritte in Open Policy Agent (OPA) Rego. Le azioni degli agenti possono essere bloccate, modificate e corrette automaticamente fornendo un feedback utile all'agente. Ulteriori vantaggi includono l'automazione reattiva per attività che non devono essere svolte dall'agente (come il linting dopo una modifica a un file).

Aggiornamenti

2025-12-10: Rilascio open source ufficiale. La roadmap sarà pubblicata nel primo trimestre del 2026.

2025-04-04: Abbiamo inoltrato la richiesta di funzionalità per Claude Code Hooks. L'allineamento in runtime richiede l'integrazione negli harness degli agenti, e ci siamo allontanati dal monitoraggio a livello di filesystem e di sistema operativo del comportamento degli agenti (primo PoC di Cupcake).

Harness per agenti supportati

Cupcake fornisce integrazioni native leggere per diversi agenti di codifica AI:

Ogni harness utilizza formati di eventi nativi. Analogamente a terraform, le policy sono separate per harness (policies/claude/, policies/cursor/, policies/factory/, policies/opencode/) per garantire chiarezza e pieno accesso alle funzionalità specifiche dell'harness. Se un determinato harness non è supportato, è perché non dispone di strumenti per l'integrazione runtime.

Binding di linguaggio

Cupcake può essere incorporato in applicazioni agente JavaScript tramite binding nativi. Ciò consente l'integrazione con framework agente basati sul web come LangChain, Google ADK, NVIDIA NIM, Vercel AI SDK e altri.

Linguaggio	Binding
TypeScript	./cupcake-ts

Come funziona

Cupcake agisce come layer di enforcement tra i tuoi agenti di codifica e il loro ambiente runtime tramite hook direttamente nel percorso delle azioni dell'agente.

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

1. Intercettazione: l'agente si prepara a eseguire un'azione/chiamata di strumento (ad es., git push, fs_write).
2. Arricchimento: Cupcake raccoglie segnali in tempo reale — fatti dell'ambiente come il branch Git corrente, lo stato della CI o i metadati del database.
3. Valutazione: l'azione e i segnali vengono impacchettati in un input JSON e valutati rispetto alle tue policy Wasm in pochi millisecondi.

Valutazione deterministica e non deterministica

Cupcake supporta due modelli di valutazione:

1. Policy deterministiche: le policy sono scritte in OPA/Rego e compilate in WebAssembly (Wasm) per una valutazione rapida e in sandbox. Consulta la guida Scrivere policy per i dettagli di implementazione.
2. LLM‑as‑Judge: per una supervisione più semplice ma più avanzata delle tue regole, Cupcake può intervenire tramite un LLM o un agente secondario per valutare come dovrebbe procedere un'azione. Consulta la guida Cupcake Watchdog per i dettagli di implementazione.

Decisioni e feedback

In base alla valutazione, Cupcake restituisce una delle cinque decisioni all'ambiente runtime dell'agente, insieme a un messaggio leggibile dall'uomo:

• Consenti: l'azione procede. Opzionalmente, Cupcake può iniettare Contesto (es. "Ricorda: sei sul branch main") per guidare il comportamento successivo senza bloccare. Nota: l'iniezione del contesto è supportata in Claude Code e Factory AI, ma non in Cursor.
• Modifica: l'azione procede con input trasformato. Le policy possono sanificare i comandi, aggiungere flag di sicurezza o imporre convenzioni prima dell'esecuzione. Nota: supportata solo in Claude Code e Factory AI.
• Blocca: l'azione viene interrotta. Cupcake invia un Feedback che spiega perché è stata bloccata (es. "I test devono passare prima del push"), consentendo all'agente di autocorreggersi.
• Avvisa: l'azione procede, ma viene registrato o mostrato un avviso.
• Richiedi revisione: l'azione viene sospesa fino all'approvazione di un essere umano.

Perché Cupcake?

Gli agenti moderni sono potenti ma incoerenti nel seguire le regole operative e di sicurezza, soprattutto quando il contesto cresce. Cupcake trasforma le regole che già mantieni (ad es., CLAUDE.md, AGENT.md, .cursor/rules) in guardrail applicabili che vengono eseguiti prima che le azioni vengano eseguite.

• Supporto multi-harness con integrazioni di prima classe per Claude Code, Cursor, Factory AI e OpenCode.
• Governance‑as‑code utilizzando OPA/Rego compilati in WebAssembly per una valutazione rapida e in sandbox.
• Controlli pronti per l'enterprise: allow/deny/review, percorsi di audit arricchiti per i SOC AI e avvisi proattivi.

Funzionalità principali

• Controllo granulare degli strumenti: previeni strumenti o argomenti specifici (ad es., bloccare rm -rf /).
• Supporto MCP: governance nativa per gli strumenti del Model Context Protocol (ad es., mcp__memory__*, mcp__github__*).
• LLM‑as‑Judge: usa un LLM o un agente secondario per valutare le azioni e ottenere una supervisione più dinamica.
• Librerie di guardrail: integrazioni di prima classe con NeMo e Invariant per controlli di contenuto e sicurezza.
• Osservabilità: tutti gli input, i segnali e le decisioni generano log strutturati e trace di valutazione per il debug.

Installazione e sviluppo con Nix

Se stai usando nix, puoi installare ed eseguire Cupcake usando il flake fornito:

Installa la CLI di Cupcake con Nix

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

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

Installa la CLI di Cupcake su NixOS

Aggiungi quanto segue al tuo flake.nix:

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

E poi aggiungi il seguente pacchetto a environment.systemPackages o home.packages:

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

Shell di sviluppo

Per lo sviluppo, puoi anche usare la dev shell fornita che include la toolchain Rust, just e altre dipendenze:

# Enter the development shell
nix develop

FAQ

Cupcake consuma token di prompt/contesto? No. Le policy vengono eseguite al di fuori del modello e restituiscono decisioni strutturate.

Cupcake è legato a un modello specifico? No. Cupcake supporta più agenti di codifica AI con integrazioni specifiche per harness.

Quanto è veloce la valutazione? Inferiore al millisecondo per le policy in cache nelle configurazioni tipiche.

Contribuire

Accogliamo con piacere i contributi! Consulta CONTRIBUTING.md per le linee guida.

Licenza

Apache 2.0

Cupcake è sviluppato da EQTYLab, con il supporto alla ricerca sulla sicurezza agentica di Trail of Bits.

Segui su X per aggiornamenti regolari.