npm package: @relayplane/policy-engine
Description: Policy Engine - governance controls and budget management for agent operations
Author: RelayPlane
Latest version: 0.1.0

# @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

```bash
pnpm add @relayplane/policy-engine
```

## Quick Start

```typescript
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:

```typescript
// 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