Veri-güdümlü guard/policy

Journal'daki __policy__ dokümanından allow/deny/require-approval guard kararı üretir — kural değişikliği kod deploy'u gerektirmez.

Ne işe yarar / ne zaman kullanılır#

Guard, her tool çağrısından önce çalışan genel bir politika kancasıdır (bkz. insan-onaylı araçlar). Elle yazılmış bir guard fonksiyonu her kural değişikliğinde yeniden deploy ister. Kuralları koda gömmek yerine veriye taşımak isterseniz — örn. " send_email aracı artık onay istesin" kararını bir operatörün Studio üzerinden anlık uygulayabilmesi gerekiyorsa — policyGuard tam bu senaryo içindir. Kurallar journal'da __policy__ anahtarında saklanır; policyGuard bu dokümanı her çağrıda canlı okur, dolayısıyla Studio'dan yapılan bir güncelleme bir sonraki tool çağrısında hemen yürürlüğe girer.

Kurulum / import#

import

import { policyGuard } from '@gnldev/durable';

Ayrı bir alt-paket yolu yok — policyGuard, evaluatePolicy ve POLICY_KEY doğrudan @gnldev/durable kök export'undan gelir.

Adım adım kullanım#

1. Guard'ı journal'a bağlayarak oluşturun ve runDurable'a verin:

agent tarafı — guard'ı bağla

import { policyGuard } from '@gnldev/durable';

const guard = policyGuard(journal, { fallback: 'allow' });
await runDurable({ runId, journal, model, tools, guard, prompt });

fallback, journal'da hiç kural yokken (veya eşleşen kural bulunamazken) uygulanacak varsayılan karardır — varsayılanı 'allow' bırakırsanız policyGuard takılıyken de doküman boşken davranış değişmez; kurallar Studio'dan eklendikçe devreye girer.

2. Kuralları Studio'dan (yazılabilir journal + operatör yetkisi gerekir) canlı düzenleyin — GET/PUT /policy:

Studio — kural güncelle

PUT /policy
{
  "rules": [
    { "tool": "send_email", "action": "require-approval", "reason": "external communication" },
    { "tool": "delete_record", "action": "deny", "reason": "irreversible" },
    { "tool": "*", "action": "allow" }
  ]
}

Her PUT, journal'daki dokümanın version alanını bir artırır ve policy.update olarak audit'e (kural setinin tamamıyla) yazılır — geçmiş sürümler denetim kaydından geri okunabilir.

Eşleşme sırası

Kural eşleşmesi önce tam tool adı, sonra '*' joker'i sırasıyla denenir; ikisi de yoksa fallback uygulanır. Bu yüzden joker kuralı listenin en sonuna koymak (yukarıdaki örnekte olduğu gibi) okunabilirlik açısından önerilir, ama eşleşme sırasını etkilemez.

API referansı#

fnpolicyGuard

journal ve opsiyonel { key, fallback } alır; her tool çağrısında __policy__ dokümanını okuyup GuardDecision üreten bir Guard döner.

fnevaluatePolicy

Saf değerlendirme fonksiyonu: (doc, toolName, fallback) → GuardDecision. Tam eşleşme, sonra joker, sonra fallback sırasıyla karar verir.

constPOLICY_KEY

Journal'daki policy dokümanının anahtarı ("__policy__") — parseJournalKey'e görünmez, özel bir sistem anahtarıdır.

typePolicyRule

{ tool: string, action: 'allow' | 'deny' | 'require-approval', reason?: string } — tool adı tam eşleşme veya '*' olabilir.

typePolicyDoc

{ version: number, rules: PolicyRule[], updatedAt?: number } — her PUT sürüm numarasını artırır.

Kapsam

Studio'daki PUT /policy, TÜM organizasyonlar için TEK GLOBAL kural seti günceller (organizasyon kapsamsızdır) — bu yüzden organizasyona bağlı bir kimlik bu uca yazamaz, yalnızca bağsız operatör güncelleyebilir; aksi halde 403 döner.