@relayplane/policy-engine

Policy Engine for RelayPlane Agent Ops - governance controls and budget management.

Features

• Policy Evaluation — Evaluate policies with deterministic priority ordering
• Budget Tracking — Spend aggregation (per-run, per-day, per-agent, per-workspace)
• Model/Provider Restrictions — Allowlist/denylist matching with scope cascade
• Policy Composition — Workspace → Team → Project → Agent hierarchy
• Ledger Integration — All policy decisions recorded with full rationale

Installation

pnpm add @relayplane/policy-engine

Quick Start

import { createPolicyEngine, MemoryPolicyStorage } from '@relayplane/policy-engine';
import { createLedger } from '@relayplane/ledger';

// Create storage and ledger
const storage = new MemoryPolicyStorage();
const ledger = createLedger();

// Create policy engine
const engine = createPolicyEngine({ storage, ledger });

// Create a budget policy
await engine.createPolicy({
  workspace_id: 'ws_123',
  name: 'Daily budget limit',
  description: 'Limit daily spending to $10',
  type: 'budget.per_day',
  enabled: true,
  priority: 100,
  scope: { applies_to: 'workspace' },
  conditions: [],
  action: {
    type: 'cap',
    parameters: { limit_usd: 10, enforce: false }
  }
});

// Evaluate request against policies
const decision = await engine.evaluate({
  workspace_id: 'ws_123',
  agent_id: 'agent_123',
  request: {
    model: 'claude-3-5-sonnet',
    provider: 'anthropic',
    estimated_cost_usd: 0.05
  }
});

if (decision.allow) {
  console.log('Request allowed');
} else {
  console.log('Request denied:', decision.reason);
}

Policy Types

| Type | Description | |------|-------------| | budget.per_run | Limit cost per individual run | | budget.per_day | Limit daily spending | | budget.per_agent | Limit spending per agent | | budget.per_workspace | Limit workspace-wide spending | | model.allowlist | Only allow specific models | | model.denylist | Block specific models | | provider.allowlist | Only allow specific providers | | provider.denylist | Block specific providers | | tool.allowlist | Only allow specific tools | | tool.denylist | Block specific tools | | context.cap | Limit context window size | | retry.limit | Limit retry attempts | | rate.limit | Limit requests per time period | | approval.gate | Require human approval |

Policy Actions

| Action | Description | |--------|-------------| | allow | Explicitly allow the request | | deny | Block the request | | warn | Allow with warning | | cap | Modify request to fit limits | | downgrade | Switch to cheaper model | | require_approval | Pause for human approval |

Condition Operators

| Operator | Description | |----------|-------------| | eq | Equal to | | neq | Not equal to | | gt | Greater than | | gte | Greater than or equal | | lt | Less than | | lte | Less than or equal | | in | Value in list | | not_in | Value not in list | | matches | Regex match |

Budget Tracking

The Policy Engine tracks spending at multiple granularities:

// Get current budget state
const state = await engine.getBudgetState('ws_123', 'day');
console.log(`Spent: $${state.spent_usd} / $${state.limit_usd}`);
console.log(`Remaining: $${state.remaining_usd}`);

// Get spend by agent
const agentSpend = await engine.getAgentSpend('ws_123', 'agent_123', {
  from: '2026-02-01',
  to: '2026-02-06'
});

API Reference

See the TypeScript declarations for full API documentation.

License

MIT