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

🛡️ Pre-Execution Authorization — Live in Your Terminal

Watch every ALLOW/DENY decision as it happens. No guesswork. No post-mortems. Real-time control over what your agent can and cannot do.

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