@predicatesystems/predicate-secure

Drop-in security wrapper for AI agents. Adds authorization, verification, and audit to any agent framework (browser-use, LangChain, Playwright, etc.) in 3 lines of code.

Installation

npm install @predicatesystems/predicate-secure

Quick Start

User Manual

import { SecureAgent } from '@predicatesystems/predicate-secure';
import { Agent } from 'browser-use';

// Wrap your existing agent
const secureAgent = new SecureAgent({
  agent: new Agent({ task: 'Buy headphones', llm: myModel }),
  policy: 'policies/shopping.yaml',
  mode: 'strict',
});

// Run with full authorization + verification loop
await secureAgent.run();

Features

• Pre-execution Authorization: Deterministic policy-based decisions before any action
• Post-execution Verification: Validate outcomes against predicate assertions
• Multi-framework Support: browser-use, LangChain, Playwright, PydanticAI, OpenClaw
• Debug Tracing: Human-readable and JSON trace output
• Minimal Dependencies: Zero production dependencies

Supported Frameworks

| Framework | Detection | Adapter | Status | |-----------|-----------|---------|--------| | browser-use | ✅ | ✅ | Full support | | Playwright | ✅ | ✅ | Full support | | LangChain | ✅ | ✅ | Full support | | PydanticAI | ✅ | ✅ | Basic support | | OpenClaw | ✅ | ✅ | Full support |

Modes

| Mode | Fail Closed | Description | |------|-------------|-------------| | strict | Yes | Deny unauthorized actions, halt on failure | | permissive | No | Log but allow unauthorized actions | | debug | No | Full trace output for development | | audit | No | Record all actions for compliance |

API

SecureAgent

import { SecureAgent, MODE_STRICT, MODE_DEBUG } from '@predicatesystems/predicate-secure';

// Create with options
const secure = new SecureAgent({
  agent: myAgent,
  policy: 'policies/security.yaml',
  mode: MODE_STRICT,
  principalId: 'agent:my-bot',
});

// Or use factory method
const secure = SecureAgent.attach(myAgent, {
  policy: 'policies/security.yaml',
  mode: MODE_DEBUG,
});

// Access properties
secure.config;      // SecureAgentConfig
secure.framework;   // Framework enum
secure.wrapped;     // WrappedAgent
secure.tracer;      // DebugTracer (in debug mode)

// Execute with authorization
await secure.run('Buy headphones under $100');

// Manual tracing
const step = secure.traceStep('click', 'button#submit');
// ... perform action ...
secure.traceStepEnd(step, true);
secure.traceVerification('url_contains', true, 'Checkout page loaded');

Framework Detection

import { FrameworkDetector, Framework } from '@predicatesystems/predicate-secure';

const detection = FrameworkDetector.detect(myAgent);
console.log(detection.framework);   // Framework.BROWSER_USE
console.log(detection.confidence);  // 1.0
console.log(detection.metadata);    // { module: 'browser_use.agent', ... }

Debug Tracing

import { DebugTracer, createDebugTracer } from '@predicatesystems/predicate-secure';

const tracer = createDebugTracer({
  format: 'console',  // or 'json'
  useColors: true,
  verbose: true,
});

tracer.traceSessionStart('browser_use', 'strict', 'policy.yaml');
tracer.traceStepStart('navigate', 'https://example.com');
tracer.tracePolicyDecision({
  action: 'navigate',
  resource: 'https://example.com',
  allowed: true,
});
tracer.traceStepEnd(1, true);
tracer.traceSessionEnd(true);

Adapters

import { createAdapter, Framework } from '@predicatesystems/predicate-secure';

// Create framework-specific adapter
const adapter = createAdapter(myAgent, Framework.BROWSER_USE, {
  tracer: myTracer,
  predicateApiKey: process.env.PREDICATE_API_KEY,
});

// Access adapter components
adapter.plugin;     // Framework-specific plugin
adapter.executor;   // LLM executor
adapter.metadata;   // Framework info

Configuration

Environment Variables

| Variable | Description | |----------|-------------| | PREDICATE_PRINCIPAL_ID | Default principal ID for authorization | | PREDICATE_AUTHORITY_POLICY_FILE | Default policy file path | | PREDICATE_AUTHORITY_SIGNING_KEY | Secret key for mandate signing | | PREDICATE_SECURE_VERBOSE | Enable verbose logging |

Policy Files

# policies/shopping.yaml
version: "1.0"
rules:
  - name: allow-shopping-sites
    effect: ALLOW
    principals:
      - "agent:shopping-bot"
    actions:
      - "navigate"
      - "click"
      - "type"
    resources:
      - "https://amazon.com/*"
      - "https://ebay.com/*"
    conditions:
      - price_under: 100

TypeScript Support

Full TypeScript support with strict types:

import type {
  SecureAgentOptions,
  SecureAgentConfig,
  WrappedAgent,
  DetectionResult,
  AdapterResult,
  TraceEvent,
  PolicyDecision,
  VerificationResult,
} from '@predicatesystems/predicate-secure';

Error Handling

import {
  AuthorizationDenied,
  VerificationFailed,
  PolicyLoadError,
  UnsupportedFrameworkError,
} from '@predicatesystems/predicate-secure';

try {
  await secureAgent.run();
} catch (error) {
  if (error instanceof AuthorizationDenied) {
    console.error('Action denied:', error.decision);
  } else if (error instanceof VerificationFailed) {
    console.error('Verification failed:', error.predicate);
  } else if (error instanceof PolicyLoadError) {
    console.error('Policy error:', error.message);
  } else if (error instanceof UnsupportedFrameworkError) {
    console.error('Unknown framework:', error.detection);
  }
}

Demo

The SDK includes a complete browser automation demo showcasing:

• Pre-execution authorization (policy-based)
• Browser automation with PredicateBrowser
• Post-execution verification (local LLM with Ollama)

# Install demo dependencies
npm run demo:install

# Set up Ollama for local LLM verification
ollama serve
ollama pull qwen2.5:7b

# Configure environment
cp demo/.env.example demo/.env

# Run the demo
npm run demo

See demo/README.md for detailed instructions and configuration options.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

License

MIT OR Apache-2.0

Related

• predicate-secure (Python) - Python SDK with full documentation on sidecar architecture, predicate authority, and more
• Predicate Studio - Cloud authorization dashboard
• @predicatesystems/runtime - Browser automation SDK with Chrome extension