agentkit-guardrails 1.0.0

package/README.md

@@ -0,0 +1,135 @@
+# agentkit-guardrails
+
+Reactive policy enforcement for AI agents. Watches metrics from **AgentLens** and automatically tightens **AgentGate** policies when thresholds are breached.
+
+## Architecture
+
+```
+┌────────────┐   webhook    ┌──────────────────────┐  Override API  ┌────────────┐
+│  AgentLens │ ──────────►  │ agentkit-guardrails   │ ─────────────► │  AgentGate │
+│  (metrics) │  breach/     │ (this service)        │  create/remove │  (policy)  │
+│            │  recovery    │                       │   overrides    │            │
+└────────────┘              └──────────────────────┘                └────────────┘
+```
+
+**Flow:**
+1. AgentLens monitors agent metrics (error rate, latency, token usage, etc.)
+2. When a threshold is breached, AgentLens sends a webhook to this service
+3. This service creates a policy override in AgentGate (e.g., require approval for all tools)
+4. When the metric recovers, AgentLens sends a recovery webhook
+5. This service removes the override, restoring normal permissions
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install agentkit-guardrails
+```
+
+### 2. Configure
+
+Create `config.yaml`:
+
+```yaml
+agentgate:
+  url: http://localhost:3002
+  apiKey: your-api-key          # optional
+
+server:
+  port: 3010                    # default: 3010
+
+rules:
+  - metric: error_rate
+    action: require_approval    # require_approval | deny | allow
+    toolPattern: "*"            # glob pattern for tools to restrict
+    ttlSeconds: 3600            # override expires after 1 hour
+    reason: "Error rate exceeded threshold"
+
+  - metric: latency_p99
+    action: deny
+    toolPattern: "external_api.*"
+    ttlSeconds: 1800
+    reason: "Latency spike detected"
+```
+
+### 3. Configure AgentLens Thresholds
+
+In AgentLens, set up threshold monitors that send webhooks to this service:
+
+```yaml
+# AgentLens threshold config
+thresholds:
+  - metric: error_rate
+    breach: 0.5
+    recovery: 0.3
+    webhook: http://localhost:3010/webhook
+```
+
+### 4. Run
+
+```bash
+npx agentkit-guardrails config.yaml
+```
+
+## Configuration Reference
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `agentgate.url` | string (URL) | ✅ | — | AgentGate API base URL |
+| `agentgate.apiKey` | string | ❌ | — | Bearer token for AgentGate API |
+| `server.port` | number | ❌ | `3010` | Port for the webhook server |
+| `rules[].metric` | string | ✅ | — | Metric name to match from webhooks |
+| `rules[].action` | enum | ✅ | — | `require_approval`, `deny`, or `allow` |
+| `rules[].toolPattern` | string | ❌ | `*` | Glob pattern for tools to restrict |
+| `rules[].ttlSeconds` | number | ❌ | `3600` | Override auto-expires after this many seconds |
+| `rules[].reason` | string | ❌ | `Guardrail triggered` | Human-readable reason stored with override |
+
+## Webhook Payload
+
+AgentLens sends POST requests to `/webhook` with this JSON body:
+
+```json
+{
+  "event": "breach",
+  "metric": "error_rate",
+  "currentValue": 0.85,
+  "threshold": 0.5,
+  "agentId": "agent-123",
+  "timestamp": "2026-02-13T09:00:00Z"
+}
+```
+
+`event` is either `"breach"` or `"recovery"`.
+
+## How Overrides Work
+
+- **Creation:** On breach, an override is created in AgentGate restricting the matching tools for the specific agent.
+- **TTL:** Overrides auto-expire after `ttlSeconds` even without recovery (safety net).
+- **Recovery:** On recovery, the override is explicitly removed.
+- **Idempotency:** Duplicate breach events for the same agent+metric are ignored — no second override is created.
+- **Independence:** Each agent+metric pair is tracked independently. A breach on `error_rate` doesn't affect `latency_p99`.
+
+## Health Check
+
+```
+GET /health → { "status": "ok" }
+```
+
+## Docker Compose Example
+
+See `docker-compose.yml` for a complete 3-service setup.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `502 AgentGate unreachable` | Check that AgentGate is running and `agentgate.url` is correct |
+| Webhook returns `ignored` | The metric name doesn't match any rule in your config |
+| Override not removed on recovery | Check AgentLens is sending recovery events; override may have TTL-expired already |
+| Duplicate overrides | This shouldn't happen — the service is idempotent. Check logs for errors |
+| Port already in use | Change `server.port` in config.yaml |
+
+## License
+
+ISC

package/dist/__tests__/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/config.test.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const config_js_1 = require("../config.js");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const tmpDir = (0, node_path_1.join)(__dirname, '../../.tmp-test');
+function writeYaml(name, content) {
+    (0, node_fs_1.mkdirSync)(tmpDir, { recursive: true });
+    const p = (0, node_path_1.join)(tmpDir, name);
+    (0, node_fs_1.writeFileSync)(p, content);
+    return p;
+}
+afterAll(() => { try {
+    (0, node_fs_1.rmSync)(tmpDir, { recursive: true });
+}
+catch { } });
+(0, vitest_1.describe)('loadConfig', () => {
+    (0, vitest_1.it)('parses valid YAML config', () => {
+        const p = writeYaml('valid.yaml', `
+agentgate:
+  url: http://localhost:3002
+server:
+  port: 3010
+rules:
+  - metric: error_rate
+    action: require_approval
+    toolPattern: "*"
+    ttlSeconds: 3600
+    reason: "Error rate high"
+`);
+        const config = (0, config_js_1.loadConfig)(p);
+        (0, vitest_1.expect)(config.agentgate.url).toBe('http://localhost:3002');
+        (0, vitest_1.expect)(config.rules).toHaveLength(1);
+        (0, vitest_1.expect)(config.rules[0].metric).toBe('error_rate');
+    });
+    (0, vitest_1.it)('rejects config with no rules', () => {
+        const p = writeYaml('norules.yaml', `
+agentgate:
+  url: http://localhost:3002
+server:
+  port: 3010
+rules: []
+`);
+        (0, vitest_1.expect)(() => (0, config_js_1.loadConfig)(p)).toThrow();
+    });
+    (0, vitest_1.it)('rejects config with invalid url', () => {
+        const p = writeYaml('badurl.yaml', `
+agentgate:
+  url: not-a-url
+server:
+  port: 3010
+rules:
+  - metric: x
+    action: deny
+`);
+        (0, vitest_1.expect)(() => (0, config_js_1.loadConfig)(p)).toThrow();
+    });
+    (0, vitest_1.it)('applies defaults for optional fields', () => {
+        const p = writeYaml('defaults.yaml', `
+agentgate:
+  url: http://localhost:3002
+server:
+  port: 3010
+rules:
+  - metric: latency
+    action: deny
+`);
+        const config = (0, config_js_1.loadConfig)(p);
+        (0, vitest_1.expect)(config.rules[0].toolPattern).toBe('*');
+        (0, vitest_1.expect)(config.rules[0].ttlSeconds).toBe(3600);
+        (0, vitest_1.expect)(config.rules[0].reason).toBe('Guardrail triggered');
+    });
+});

package/dist/__tests__/gate-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/gate-client.test.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const gate_client_js_1 = require("../gate-client.js");
+const originalFetch = globalThis.fetch;
+(0, vitest_1.describe)('GateClient', () => {
+    let mockFetch;
+    (0, vitest_1.beforeEach)(() => {
+        mockFetch = vitest_1.vi.fn();
+        globalThis.fetch = mockFetch;
+    });
+    (0, vitest_1.afterEach)(() => {
+        globalThis.fetch = originalFetch;
+    });
+    (0, vitest_1.it)('createOverride sends POST and returns result', async () => {
+        mockFetch.mockResolvedValue({ ok: true, json: () => Promise.resolve({ id: 'ovr-1', agentId: 'a1', toolPattern: '*', action: 'deny', reason: 'test', ttlSeconds: 60 }) });
+        const client = new gate_client_js_1.GateClient('http://localhost:3002', 'key123');
+        const result = await client.createOverride({ agentId: 'a1', toolPattern: '*', action: 'deny', reason: 'test', ttlSeconds: 60 });
+        (0, vitest_1.expect)(result.id).toBe('ovr-1');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3002/api/overrides', vitest_1.expect.objectContaining({ method: 'POST' }));
+        // Check auth header
+        const headers = mockFetch.mock.calls[0][1].headers;
+        (0, vitest_1.expect)(headers['Authorization']).toBe('Bearer key123');
+    });
+    (0, vitest_1.it)('removeOverride sends DELETE', async () => {
+        mockFetch.mockResolvedValue({ ok: true });
+        const client = new gate_client_js_1.GateClient('http://localhost:3002');
+        await client.removeOverride('ovr-1');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3002/api/overrides/ovr-1', vitest_1.expect.objectContaining({ method: 'DELETE' }));
+    });
+    (0, vitest_1.it)('throws on non-ok response', async () => {
+        mockFetch.mockResolvedValue({ ok: false, status: 500 });
+        const client = new gate_client_js_1.GateClient('http://localhost:3002');
+        await (0, vitest_1.expect)(client.listOverrides()).rejects.toThrow('500');
+    });
+});

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration.test.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const server_js_1 = require("../server.js");
+const multiRuleConfig = {
+    agentgate: { url: 'http://localhost:3002' },
+    server: { port: 0 },
+    rules: [
+        { metric: 'error_rate', action: 'require_approval', toolPattern: '*', ttlSeconds: 3600, reason: 'Error rate high' },
+        { metric: 'latency_p99', action: 'deny', toolPattern: 'external_api.*', ttlSeconds: 1800, reason: 'Latency spike' },
+    ],
+};
+function makeClient() {
+    let nextId = 1;
+    return {
+        createOverride: vitest_1.vi.fn().mockImplementation(async () => ({
+            id: `ovr-${nextId++}`,
+            agentId: 'a',
+            toolPattern: '*',
+            action: 'require_approval',
+            reason: 'test',
+            ttlSeconds: 3600,
+        })),
+        removeOverride: vitest_1.vi.fn().mockResolvedValue(undefined),
+        listOverrides: vitest_1.vi.fn().mockResolvedValue([]),
+    };
+}
+const webhook = (event, metric, agentId = 'agent-1') => ({
+    event,
+    metric,
+    currentValue: event === 'breach' ? 0.9 : 0.1,
+    threshold: 0.5,
+    agentId,
+    timestamp: new Date().toISOString(),
+});
+(0, vitest_1.describe)('integration: full breach → recovery → idempotency flow', () => {
+    (0, vitest_1.it)('handles breach, recovery, and duplicate breach end-to-end', async () => {
+        const client = makeClient();
+        const { app, activeOverrides } = (0, server_js_1.buildServer)(multiRuleConfig, client);
+        // 1. Breach → override created
+        const r1 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+        (0, vitest_1.expect)(r1.statusCode).toBe(201);
+        (0, vitest_1.expect)(JSON.parse(r1.body).status).toBe('override_created');
+        (0, vitest_1.expect)(activeOverrides.size).toBe(1);
+        // 2. Recovery → override removed
+        const r2 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('recovery', 'error_rate') });
+        (0, vitest_1.expect)(r2.statusCode).toBe(200);
+        (0, vitest_1.expect)(JSON.parse(r2.body).status).toBe('override_removed');
+        (0, vitest_1.expect)(activeOverrides.size).toBe(0);
+        // 3. Breach again → new override created (not duplicate since previous was removed)
+        const r3 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+        (0, vitest_1.expect)(r3.statusCode).toBe(201);
+        // 4. Duplicate breach → idempotent
+        const r4 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+        (0, vitest_1.expect)(r4.statusCode).toBe(200);
+        (0, vitest_1.expect)(JSON.parse(r4.body).status).toBe('already_active');
+        (0, vitest_1.expect)(client.createOverride).toHaveBeenCalledTimes(2); // only 2 creates total
+    });
+    (0, vitest_1.it)('handles multiple independent rules for different metrics', async () => {
+        const client = makeClient();
+        const { app, activeOverrides } = (0, server_js_1.buildServer)(multiRuleConfig, client);
+        // Breach error_rate
+        const r1 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+        (0, vitest_1.expect)(r1.statusCode).toBe(201);
+        // Breach latency_p99 — independent rule
+        const r2 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'latency_p99') });
+        (0, vitest_1.expect)(r2.statusCode).toBe(201);
+        // Both active
+        (0, vitest_1.expect)(activeOverrides.size).toBe(2);
+        (0, vitest_1.expect)(client.createOverride).toHaveBeenCalledTimes(2);
+        // Verify correct toolPatterns were passed
+        const calls = client.createOverride.mock.calls;
+        (0, vitest_1.expect)(calls[0][0].toolPattern).toBe('*');
+        (0, vitest_1.expect)(calls[1][0].toolPattern).toBe('external_api.*');
+        // Recover one, other stays
+        await app.inject({ method: 'POST', url: '/webhook', payload: webhook('recovery', 'error_rate') });
+        (0, vitest_1.expect)(activeOverrides.size).toBe(1);
+        (0, vitest_1.expect)(activeOverrides.has('agent-1::latency_p99')).toBe(true);
+    });
+});
+(0, vitest_1.describe)('integration: health check', () => {
+    (0, vitest_1.it)('responds to health check', async () => {
+        const { app } = (0, server_js_1.buildServer)(multiRuleConfig, makeClient());
+        const res = await app.inject({ method: 'GET', url: '/health' });
+        (0, vitest_1.expect)(res.statusCode).toBe(200);
+        (0, vitest_1.expect)(JSON.parse(res.body)).toEqual({ status: 'ok' });
+    });
+});

package/dist/__tests__/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/server.test.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const server_js_1 = require("../server.js");
+const testConfig = {
+    agentgate: { url: 'http://localhost:3002' },
+    server: { port: 0 },
+    rules: [
+        { metric: 'error_rate', action: 'require_approval', toolPattern: '*', ttlSeconds: 3600, reason: 'Error rate high' },
+    ],
+};
+function makeClient() {
+    return {
+        createOverride: vitest_1.vi.fn().mockResolvedValue({ id: 'ovr-123', agentId: 'agent-1', toolPattern: '*', action: 'require_approval', reason: 'test', ttlSeconds: 3600 }),
+        removeOverride: vitest_1.vi.fn().mockResolvedValue(undefined),
+        listOverrides: vitest_1.vi.fn().mockResolvedValue([]),
+    };
+}
+const breach = (metric = 'error_rate') => ({ event: 'breach', metric, currentValue: 0.9, threshold: 0.5, agentId: 'agent-1', timestamp: new Date().toISOString() });
+const recovery = (metric = 'error_rate') => ({ event: 'recovery', metric, currentValue: 0.3, threshold: 0.5, agentId: 'agent-1', timestamp: new Date().toISOString() });
+(0, vitest_1.describe)('webhook handler', () => {
+    (0, vitest_1.it)('rejects invalid payload', async () => {
+        const { app } = (0, server_js_1.buildServer)(testConfig, makeClient());
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: { bad: true } });
+        (0, vitest_1.expect)(res.statusCode).toBe(400);
+    });
+    (0, vitest_1.it)('creates override on breach event', async () => {
+        const client = makeClient();
+        const { app, activeOverrides } = (0, server_js_1.buildServer)(testConfig, client);
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+        (0, vitest_1.expect)(res.statusCode).toBe(201);
+        (0, vitest_1.expect)(client.createOverride).toHaveBeenCalledOnce();
+        (0, vitest_1.expect)(activeOverrides.get('agent-1::error_rate')).toBe('ovr-123');
+    });
+    (0, vitest_1.it)('is idempotent — duplicate breach does not create second override', async () => {
+        const client = makeClient();
+        const { app } = (0, server_js_1.buildServer)(testConfig, client);
+        await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+        (0, vitest_1.expect)(res.statusCode).toBe(200);
+        (0, vitest_1.expect)(JSON.parse(res.body).status).toBe('already_active');
+        (0, vitest_1.expect)(client.createOverride).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)('removes override on recovery event', async () => {
+        const client = makeClient();
+        const { app, activeOverrides } = (0, server_js_1.buildServer)(testConfig, client);
+        await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: recovery() });
+        (0, vitest_1.expect)(res.statusCode).toBe(200);
+        (0, vitest_1.expect)(JSON.parse(res.body).status).toBe('override_removed');
+        (0, vitest_1.expect)(client.removeOverride).toHaveBeenCalledWith('ovr-123');
+        (0, vitest_1.expect)(activeOverrides.size).toBe(0);
+    });
+    (0, vitest_1.it)('returns ignored for unknown metric', async () => {
+        const { app } = (0, server_js_1.buildServer)(testConfig, makeClient());
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach('unknown_metric') });
+        (0, vitest_1.expect)(res.statusCode).toBe(200);
+        (0, vitest_1.expect)(JSON.parse(res.body).status).toBe('ignored');
+    });
+    (0, vitest_1.it)('returns 502 when AgentGate is unreachable on breach', async () => {
+        const client = makeClient();
+        client.createOverride.mockRejectedValue(new Error('connection refused'));
+        const { app } = (0, server_js_1.buildServer)(testConfig, client);
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+        (0, vitest_1.expect)(res.statusCode).toBe(502);
+    });
+    (0, vitest_1.it)('returns 502 when AgentGate is unreachable on recovery', async () => {
+        const client = makeClient();
+        client.removeOverride.mockRejectedValue(new Error('connection refused'));
+        const { app, activeOverrides } = (0, server_js_1.buildServer)(testConfig, client);
+        activeOverrides.set('agent-1::error_rate', 'ovr-123');
+        const res = await app.inject({ method: 'POST', url: '/webhook', payload: recovery() });
+        (0, vitest_1.expect)(res.statusCode).toBe(502);
+    });
+});

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+declare const RuleSchema: z.ZodObject<{
+    metric: z.ZodString;
+    action: z.ZodEnum<{
+        require_approval: "require_approval";
+        deny: "deny";
+        allow: "allow";
+    }>;
+    toolPattern: z.ZodDefault<z.ZodString>;
+    ttlSeconds: z.ZodDefault<z.ZodNumber>;
+    reason: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+declare const ConfigSchema: z.ZodObject<{
+    agentgate: z.ZodObject<{
+        url: z.ZodString;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    server: z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    rules: z.ZodArray<z.ZodObject<{
+        metric: z.ZodString;
+        action: z.ZodEnum<{
+            require_approval: "require_approval";
+            deny: "deny";
+            allow: "allow";
+        }>;
+        toolPattern: z.ZodDefault<z.ZodString>;
+        ttlSeconds: z.ZodDefault<z.ZodNumber>;
+        reason: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+export type Rule = z.infer<typeof RuleSchema>;
+export declare function loadConfig(path: string): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const zod_1 = require("zod");
+const node_fs_1 = require("node:fs");
+const yaml_1 = require("yaml");
+const RuleSchema = zod_1.z.object({
+    metric: zod_1.z.string(),
+    action: zod_1.z.enum(['require_approval', 'deny', 'allow']),
+    toolPattern: zod_1.z.string().default('*'),
+    ttlSeconds: zod_1.z.number().positive().default(3600),
+    reason: zod_1.z.string().default('Guardrail triggered'),
+});
+const ConfigSchema = zod_1.z.object({
+    agentgate: zod_1.z.object({
+        url: zod_1.z.string().url(),
+        apiKey: zod_1.z.string().optional(),
+    }),
+    server: zod_1.z.object({
+        port: zod_1.z.number().int().positive().default(3010),
+    }),
+    rules: zod_1.z.array(RuleSchema).min(1),
+});
+function loadConfig(path) {
+    const raw = (0, node_fs_1.readFileSync)(path, 'utf-8');
+    const parsed = (0, yaml_1.parse)(raw);
+    return ConfigSchema.parse(parsed);
+}

package/dist/gate-client.d.ts

@@ -0,0 +1,19 @@
+export interface OverrideRequest {
+    agentId: string;
+    toolPattern: string;
+    action: string;
+    reason: string;
+    ttlSeconds: number;
+}
+export interface Override extends OverrideRequest {
+    id: string;
+}
+export declare class GateClient {
+    private baseUrl;
+    private apiKey?;
+    constructor(baseUrl: string, apiKey?: string | undefined);
+    private headers;
+    createOverride(override: OverrideRequest): Promise<Override>;
+    removeOverride(id: string): Promise<void>;
+    listOverrides(): Promise<Override[]>;
+}

package/dist/gate-client.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GateClient = void 0;
+class GateClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    headers() {
+        const h = { 'Content-Type': 'application/json' };
+        if (this.apiKey)
+            h['Authorization'] = `Bearer ${this.apiKey}`;
+        return h;
+    }
+    async createOverride(override) {
+        const res = await fetch(`${this.baseUrl}/api/overrides`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(override),
+        });
+        if (!res.ok)
+            throw new Error(`AgentGate POST /api/overrides failed: ${res.status}`);
+        return res.json();
+    }
+    async removeOverride(id) {
+        const res = await fetch(`${this.baseUrl}/api/overrides/${id}`, {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`AgentGate DELETE /api/overrides/${id} failed: ${res.status}`);
+    }
+    async listOverrides() {
+        const res = await fetch(`${this.baseUrl}/api/overrides`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`AgentGate GET /api/overrides failed: ${res.status}`);
+        return res.json();
+    }
+}
+exports.GateClient = GateClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_js_1 = require("./config.js");
+const server_js_1 = require("./server.js");
+const gate_client_js_1 = require("./gate-client.js");
+const configPath = process.argv[2] || 'config.yaml';
+async function main() {
+    const config = (0, config_js_1.loadConfig)(configPath);
+    const gateClient = new gate_client_js_1.GateClient(config.agentgate.url, config.agentgate.apiKey);
+    const { app } = (0, server_js_1.buildServer)(config, gateClient);
+    await app.listen({ port: config.server.port, host: '0.0.0.0' });
+    console.log(`agentkit-guardrails listening on port ${config.server.port}`);
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+import { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import { Config } from './config.js';
+import { GateClient } from './gate-client.js';
+declare const WebhookPayload: z.ZodObject<{
+    event: z.ZodEnum<{
+        breach: "breach";
+        recovery: "recovery";
+    }>;
+    metric: z.ZodString;
+    currentValue: z.ZodNumber;
+    threshold: z.ZodNumber;
+    agentId: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WebhookEvent = z.infer<typeof WebhookPayload>;
+export interface GuardrailsServer {
+    app: FastifyInstance;
+    activeOverrides: Map<string, string>;
+}
+export declare function buildServer(config: Config, gateClient?: GateClient): GuardrailsServer;
+export {};

package/dist/server.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServer = buildServer;
+const fastify_1 = __importDefault(require("fastify"));
+const zod_1 = require("zod");
+const gate_client_js_1 = require("./gate-client.js");
+const WebhookPayload = zod_1.z.object({
+    event: zod_1.z.enum(['breach', 'recovery']),
+    metric: zod_1.z.string(),
+    currentValue: zod_1.z.number(),
+    threshold: zod_1.z.number(),
+    agentId: zod_1.z.string(),
+    timestamp: zod_1.z.string(),
+});
+function matchRule(metric, rules) {
+    return rules.find((r) => r.metric === metric);
+}
+function overrideKey(agentId, metric) {
+    return `${agentId}::${metric}`;
+}
+function buildServer(config, gateClient) {
+    const app = (0, fastify_1.default)({ logger: false });
+    const client = gateClient ?? new gate_client_js_1.GateClient(config.agentgate.url, config.agentgate.apiKey);
+    const activeOverrides = new Map();
+    app.post('/webhook', async (request, reply) => {
+        const parseResult = WebhookPayload.safeParse(request.body);
+        if (!parseResult.success) {
+            return reply.status(400).send({ error: 'Invalid payload', details: parseResult.error.issues });
+        }
+        const payload = parseResult.data;
+        const rule = matchRule(payload.metric, config.rules);
+        if (!rule) {
+            return reply.status(200).send({ status: 'ignored', reason: 'no matching rule' });
+        }
+        const key = overrideKey(payload.agentId, payload.metric);
+        if (payload.event === 'breach') {
+            if (activeOverrides.has(key)) {
+                return reply.status(200).send({ status: 'already_active', overrideId: activeOverrides.get(key) });
+            }
+            try {
+                const override = await client.createOverride({
+                    agentId: payload.agentId,
+                    toolPattern: rule.toolPattern,
+                    action: rule.action,
+                    reason: rule.reason,
+                    ttlSeconds: rule.ttlSeconds,
+                });
+                if (!override || !override.id) {
+                    throw new Error('Invalid response from AgentGate: missing override id');
+                }
+                activeOverrides.set(key, override.id);
+                return reply.status(201).send({ status: 'override_created', overrideId: override.id });
+            }
+            catch (err) {
+                return reply.status(502).send({ error: 'AgentGate unreachable', detail: String(err) });
+            }
+        }
+        if (payload.event === 'recovery') {
+            const overrideId = activeOverrides.get(key);
+            if (!overrideId) {
+                return reply.status(200).send({ status: 'no_active_override' });
+            }
+            try {
+                await client.removeOverride(overrideId);
+                activeOverrides.delete(key);
+                return reply.status(200).send({ status: 'override_removed', overrideId });
+            }
+            catch (err) {
+                return reply.status(502).send({ error: 'AgentGate unreachable', detail: String(err) });
+            }
+        }
+    });
+    app.get('/health', async () => ({ status: 'ok' }));
+    return { app, activeOverrides };
+}

package/docker-compose.yml

@@ -0,0 +1,27 @@
+services:
+  agentgate:
+    image: agentgate:latest
+    ports:
+      - "3002:3002"
+    environment:
+      - PORT=3002
+
+  agentlens:
+    image: agentlens:latest
+    ports:
+      - "3001:3001"
+    environment:
+      - PORT=3001
+      - WEBHOOK_URL=http://guardrails:3010/webhook
+    depends_on:
+      - agentgate
+
+  guardrails:
+    image: agentkit-guardrails:latest
+    ports:
+      - "3010:3010"
+    volumes:
+      - ./config.yaml:/app/config.yaml:ro
+    command: ["node", "dist/index.js", "/app/config.yaml"]
+    depends_on:
+      - agentgate

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "agentkit-guardrails",
+  "version": "1.0.0",
+  "description": "Reactive policy enforcement: auto-tighten AgentGate policies when AgentLens metrics breach thresholds",
+  "main": "dist/index.js",
+  "bin": {
+    "agentkit-guardrails": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["agentkit", "guardrails", "agentgate", "agentlens", "policy", "ai-safety"],
+  "author": "Amit Paz",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amitpaz/agentkit-guardrails"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "fastify": "^5.7.4",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/__tests__/config.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { loadConfig } from '../config.js';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const tmpDir = join(__dirname, '../../.tmp-test');
+
+function writeYaml(name: string, content: string): string {
+  mkdirSync(tmpDir, { recursive: true });
+  const p = join(tmpDir, name);
+  writeFileSync(p, content);
+  return p;
+}
+
+afterAll(() => { try { rmSync(tmpDir, { recursive: true }); } catch {} });
+
+describe('loadConfig', () => {
+  it('parses valid YAML config', () => {
+    const p = writeYaml('valid.yaml', `
+agentgate:
+  url: http://localhost:3002
+server:
+  port: 3010
+rules:
+  - metric: error_rate
+    action: require_approval
+    toolPattern: "*"
+    ttlSeconds: 3600
+    reason: "Error rate high"
+`);
+    const config = loadConfig(p);
+    expect(config.agentgate.url).toBe('http://localhost:3002');
+    expect(config.rules).toHaveLength(1);
+    expect(config.rules[0].metric).toBe('error_rate');
+  });
+
+  it('rejects config with no rules', () => {
+    const p = writeYaml('norules.yaml', `
+agentgate:
+  url: http://localhost:3002
+server:
+  port: 3010
+rules: []
+`);
+    expect(() => loadConfig(p)).toThrow();
+  });
+
+  it('rejects config with invalid url', () => {
+    const p = writeYaml('badurl.yaml', `
+agentgate:
+  url: not-a-url
+server:
+  port: 3010
+rules:
+  - metric: x
+    action: deny
+`);
+    expect(() => loadConfig(p)).toThrow();
+  });
+
+  it('applies defaults for optional fields', () => {
+    const p = writeYaml('defaults.yaml', `
+agentgate:
+  url: http://localhost:3002
+server:
+  port: 3010
+rules:
+  - metric: latency
+    action: deny
+`);
+    const config = loadConfig(p);
+    expect(config.rules[0].toolPattern).toBe('*');
+    expect(config.rules[0].ttlSeconds).toBe(3600);
+    expect(config.rules[0].reason).toBe('Guardrail triggered');
+  });
+});

package/src/__tests__/gate-client.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { GateClient } from '../gate-client.js';
+
+const originalFetch = globalThis.fetch;
+
+describe('GateClient', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    globalThis.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('createOverride sends POST and returns result', async () => {
+    mockFetch.mockResolvedValue({ ok: true, json: () => Promise.resolve({ id: 'ovr-1', agentId: 'a1', toolPattern: '*', action: 'deny', reason: 'test', ttlSeconds: 60 }) });
+    const client = new GateClient('http://localhost:3002', 'key123');
+    const result = await client.createOverride({ agentId: 'a1', toolPattern: '*', action: 'deny', reason: 'test', ttlSeconds: 60 });
+    expect(result.id).toBe('ovr-1');
+    expect(mockFetch).toHaveBeenCalledWith('http://localhost:3002/api/overrides', expect.objectContaining({ method: 'POST' }));
+    // Check auth header
+    const headers = mockFetch.mock.calls[0][1].headers;
+    expect(headers['Authorization']).toBe('Bearer key123');
+  });
+
+  it('removeOverride sends DELETE', async () => {
+    mockFetch.mockResolvedValue({ ok: true });
+    const client = new GateClient('http://localhost:3002');
+    await client.removeOverride('ovr-1');
+    expect(mockFetch).toHaveBeenCalledWith('http://localhost:3002/api/overrides/ovr-1', expect.objectContaining({ method: 'DELETE' }));
+  });
+
+  it('throws on non-ok response', async () => {
+    mockFetch.mockResolvedValue({ ok: false, status: 500 });
+    const client = new GateClient('http://localhost:3002');
+    await expect(client.listOverrides()).rejects.toThrow('500');
+  });
+});

package/src/__tests__/integration.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildServer } from '../server.js';
+import { Config } from '../config.js';
+import { GateClient } from '../gate-client.js';
+
+const multiRuleConfig: Config = {
+  agentgate: { url: 'http://localhost:3002' },
+  server: { port: 0 },
+  rules: [
+    { metric: 'error_rate', action: 'require_approval', toolPattern: '*', ttlSeconds: 3600, reason: 'Error rate high' },
+    { metric: 'latency_p99', action: 'deny', toolPattern: 'external_api.*', ttlSeconds: 1800, reason: 'Latency spike' },
+  ],
+};
+
+function makeClient() {
+  let nextId = 1;
+  return {
+    createOverride: vi.fn().mockImplementation(async () => ({
+      id: `ovr-${nextId++}`,
+      agentId: 'a',
+      toolPattern: '*',
+      action: 'require_approval',
+      reason: 'test',
+      ttlSeconds: 3600,
+    })),
+    removeOverride: vi.fn().mockResolvedValue(undefined),
+    listOverrides: vi.fn().mockResolvedValue([]),
+  } as unknown as GateClient;
+}
+
+const webhook = (event: string, metric: string, agentId = 'agent-1') => ({
+  event,
+  metric,
+  currentValue: event === 'breach' ? 0.9 : 0.1,
+  threshold: 0.5,
+  agentId,
+  timestamp: new Date().toISOString(),
+});
+
+describe('integration: full breach → recovery → idempotency flow', () => {
+  it('handles breach, recovery, and duplicate breach end-to-end', async () => {
+    const client = makeClient();
+    const { app, activeOverrides } = buildServer(multiRuleConfig, client);
+
+    // 1. Breach → override created
+    const r1 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+    expect(r1.statusCode).toBe(201);
+    expect(JSON.parse(r1.body).status).toBe('override_created');
+    expect(activeOverrides.size).toBe(1);
+
+    // 2. Recovery → override removed
+    const r2 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('recovery', 'error_rate') });
+    expect(r2.statusCode).toBe(200);
+    expect(JSON.parse(r2.body).status).toBe('override_removed');
+    expect(activeOverrides.size).toBe(0);
+
+    // 3. Breach again → new override created (not duplicate since previous was removed)
+    const r3 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+    expect(r3.statusCode).toBe(201);
+
+    // 4. Duplicate breach → idempotent
+    const r4 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+    expect(r4.statusCode).toBe(200);
+    expect(JSON.parse(r4.body).status).toBe('already_active');
+    expect(client.createOverride).toHaveBeenCalledTimes(2); // only 2 creates total
+  });
+
+  it('handles multiple independent rules for different metrics', async () => {
+    const client = makeClient();
+    const { app, activeOverrides } = buildServer(multiRuleConfig, client);
+
+    // Breach error_rate
+    const r1 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'error_rate') });
+    expect(r1.statusCode).toBe(201);
+
+    // Breach latency_p99 — independent rule
+    const r2 = await app.inject({ method: 'POST', url: '/webhook', payload: webhook('breach', 'latency_p99') });
+    expect(r2.statusCode).toBe(201);
+
+    // Both active
+    expect(activeOverrides.size).toBe(2);
+    expect(client.createOverride).toHaveBeenCalledTimes(2);
+
+    // Verify correct toolPatterns were passed
+    const calls = (client.createOverride as any).mock.calls;
+    expect(calls[0][0].toolPattern).toBe('*');
+    expect(calls[1][0].toolPattern).toBe('external_api.*');
+
+    // Recover one, other stays
+    await app.inject({ method: 'POST', url: '/webhook', payload: webhook('recovery', 'error_rate') });
+    expect(activeOverrides.size).toBe(1);
+    expect(activeOverrides.has('agent-1::latency_p99')).toBe(true);
+  });
+});
+
+describe('integration: health check', () => {
+  it('responds to health check', async () => {
+    const { app } = buildServer(multiRuleConfig, makeClient());
+    const res = await app.inject({ method: 'GET', url: '/health' });
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ status: 'ok' });
+  });
+});

package/src/__tests__/server.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildServer } from '../server.js';
+import { Config } from '../config.js';
+import { GateClient } from '../gate-client.js';
+
+const testConfig: Config = {
+  agentgate: { url: 'http://localhost:3002' },
+  server: { port: 0 },
+  rules: [
+    { metric: 'error_rate', action: 'require_approval', toolPattern: '*', ttlSeconds: 3600, reason: 'Error rate high' },
+  ],
+};
+
+function makeClient() {
+  return {
+    createOverride: vi.fn().mockResolvedValue({ id: 'ovr-123', agentId: 'agent-1', toolPattern: '*', action: 'require_approval', reason: 'test', ttlSeconds: 3600 }),
+    removeOverride: vi.fn().mockResolvedValue(undefined),
+    listOverrides: vi.fn().mockResolvedValue([]),
+  } as unknown as GateClient;
+}
+
+const breach = (metric = 'error_rate') => ({ event: 'breach', metric, currentValue: 0.9, threshold: 0.5, agentId: 'agent-1', timestamp: new Date().toISOString() });
+const recovery = (metric = 'error_rate') => ({ event: 'recovery', metric, currentValue: 0.3, threshold: 0.5, agentId: 'agent-1', timestamp: new Date().toISOString() });
+
+describe('webhook handler', () => {
+  it('rejects invalid payload', async () => {
+    const { app } = buildServer(testConfig, makeClient());
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: { bad: true } });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('creates override on breach event', async () => {
+    const client = makeClient();
+    const { app, activeOverrides } = buildServer(testConfig, client);
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+    expect(res.statusCode).toBe(201);
+    expect(client.createOverride).toHaveBeenCalledOnce();
+    expect(activeOverrides.get('agent-1::error_rate')).toBe('ovr-123');
+  });
+
+  it('is idempotent — duplicate breach does not create second override', async () => {
+    const client = makeClient();
+    const { app } = buildServer(testConfig, client);
+    await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).status).toBe('already_active');
+    expect(client.createOverride).toHaveBeenCalledTimes(1);
+  });
+
+  it('removes override on recovery event', async () => {
+    const client = makeClient();
+    const { app, activeOverrides } = buildServer(testConfig, client);
+    await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: recovery() });
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).status).toBe('override_removed');
+    expect(client.removeOverride).toHaveBeenCalledWith('ovr-123');
+    expect(activeOverrides.size).toBe(0);
+  });
+
+  it('returns ignored for unknown metric', async () => {
+    const { app } = buildServer(testConfig, makeClient());
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach('unknown_metric') });
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).status).toBe('ignored');
+  });
+
+  it('returns 502 when AgentGate is unreachable on breach', async () => {
+    const client = makeClient();
+    (client.createOverride as any).mockRejectedValue(new Error('connection refused'));
+    const { app } = buildServer(testConfig, client);
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: breach() });
+    expect(res.statusCode).toBe(502);
+  });
+
+  it('returns 502 when AgentGate is unreachable on recovery', async () => {
+    const client = makeClient();
+    (client.removeOverride as any).mockRejectedValue(new Error('connection refused'));
+    const { app, activeOverrides } = buildServer(testConfig, client);
+    activeOverrides.set('agent-1::error_rate', 'ovr-123');
+    const res = await app.inject({ method: 'POST', url: '/webhook', payload: recovery() });
+    expect(res.statusCode).toBe(502);
+  });
+});

package/src/config.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+
+const RuleSchema = z.object({
+  metric: z.string(),
+  action: z.enum(['require_approval', 'deny', 'allow']),
+  toolPattern: z.string().default('*'),
+  ttlSeconds: z.number().positive().default(3600),
+  reason: z.string().default('Guardrail triggered'),
+});
+
+const ConfigSchema = z.object({
+  agentgate: z.object({
+    url: z.string().url(),
+    apiKey: z.string().optional(),
+  }),
+  server: z.object({
+    port: z.number().int().positive().default(3010),
+  }),
+  rules: z.array(RuleSchema).min(1),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+export type Rule = z.infer<typeof RuleSchema>;
+
+export function loadConfig(path: string): Config {
+  const raw = readFileSync(path, 'utf-8');
+  const parsed = parseYaml(raw);
+  return ConfigSchema.parse(parsed);
+}

package/src/gate-client.ts

@@ -0,0 +1,50 @@
+export interface OverrideRequest {
+  agentId: string;
+  toolPattern: string;
+  action: string;
+  reason: string;
+  ttlSeconds: number;
+}
+
+export interface Override extends OverrideRequest {
+  id: string;
+}
+
+export class GateClient {
+  constructor(
+    private baseUrl: string,
+    private apiKey?: string,
+  ) {}
+
+  private headers(): Record<string, string> {
+    const h: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (this.apiKey) h['Authorization'] = `Bearer ${this.apiKey}`;
+    return h;
+  }
+
+  async createOverride(override: OverrideRequest): Promise<Override> {
+    const res = await fetch(`${this.baseUrl}/api/overrides`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify(override),
+    });
+    if (!res.ok) throw new Error(`AgentGate POST /api/overrides failed: ${res.status}`);
+    return res.json() as Promise<Override>;
+  }
+
+  async removeOverride(id: string): Promise<void> {
+    const res = await fetch(`${this.baseUrl}/api/overrides/${id}`, {
+      method: 'DELETE',
+      headers: this.headers(),
+    });
+    if (!res.ok) throw new Error(`AgentGate DELETE /api/overrides/${id} failed: ${res.status}`);
+  }
+
+  async listOverrides(): Promise<Override[]> {
+    const res = await fetch(`${this.baseUrl}/api/overrides`, {
+      headers: this.headers(),
+    });
+    if (!res.ok) throw new Error(`AgentGate GET /api/overrides failed: ${res.status}`);
+    return res.json() as Promise<Override[]>;
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { loadConfig } from './config.js';
+import { buildServer } from './server.js';
+import { GateClient } from './gate-client.js';
+
+const configPath = process.argv[2] || 'config.yaml';
+
+async function main() {
+  const config = loadConfig(configPath);
+  const gateClient = new GateClient(config.agentgate.url, config.agentgate.apiKey);
+  const { app } = buildServer(config, gateClient);
+
+  await app.listen({ port: config.server.port, host: '0.0.0.0' });
+  console.log(`agentkit-guardrails listening on port ${config.server.port}`);
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,92 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import { Config, Rule } from './config.js';
+import { GateClient } from './gate-client.js';
+
+const WebhookPayload = z.object({
+  event: z.enum(['breach', 'recovery']),
+  metric: z.string(),
+  currentValue: z.number(),
+  threshold: z.number(),
+  agentId: z.string(),
+  timestamp: z.string(),
+});
+
+export type WebhookEvent = z.infer<typeof WebhookPayload>;
+
+function matchRule(metric: string, rules: Rule[]): Rule | undefined {
+  return rules.find((r) => r.metric === metric);
+}
+
+function overrideKey(agentId: string, metric: string): string {
+  return `${agentId}::${metric}`;
+}
+
+export interface GuardrailsServer {
+  app: FastifyInstance;
+  activeOverrides: Map<string, string>;
+}
+
+export function buildServer(config: Config, gateClient?: GateClient): GuardrailsServer {
+  const app = Fastify({ logger: false });
+  const client = gateClient ?? new GateClient(config.agentgate.url, config.agentgate.apiKey);
+  const activeOverrides = new Map<string, string>();
+
+  app.post('/webhook', async (request, reply) => {
+    const parseResult = WebhookPayload.safeParse(request.body);
+    if (!parseResult.success) {
+      return reply.status(400).send({ error: 'Invalid payload', details: parseResult.error.issues });
+    }
+
+    const payload = parseResult.data;
+    const rule = matchRule(payload.metric, config.rules);
+
+    if (!rule) {
+      return reply.status(200).send({ status: 'ignored', reason: 'no matching rule' });
+    }
+
+    const key = overrideKey(payload.agentId, payload.metric);
+
+    if (payload.event === 'breach') {
+      if (activeOverrides.has(key)) {
+        return reply.status(200).send({ status: 'already_active', overrideId: activeOverrides.get(key) });
+      }
+
+      try {
+        const override = await client.createOverride({
+          agentId: payload.agentId,
+          toolPattern: rule.toolPattern,
+          action: rule.action,
+          reason: rule.reason,
+          ttlSeconds: rule.ttlSeconds,
+        });
+        if (!override || !override.id) {
+          throw new Error('Invalid response from AgentGate: missing override id');
+        }
+        activeOverrides.set(key, override.id);
+        return reply.status(201).send({ status: 'override_created', overrideId: override.id });
+      } catch (err) {
+        return reply.status(502).send({ error: 'AgentGate unreachable', detail: String(err) });
+      }
+    }
+
+    if (payload.event === 'recovery') {
+      const overrideId = activeOverrides.get(key);
+      if (!overrideId) {
+        return reply.status(200).send({ status: 'no_active_override' });
+      }
+
+      try {
+        await client.removeOverride(overrideId);
+        activeOverrides.delete(key);
+        return reply.status(200).send({ status: 'override_removed', overrideId });
+      } catch (err) {
+        return reply.status(502).send({ error: 'AgentGate unreachable', detail: String(err) });
+      }
+    }
+  });
+
+  app.get('/health', async () => ({ status: 'ok' }));
+
+  return { app, activeOverrides };
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});