demo works

README.md

@@ -10,6 +10,8 @@ npm install @PredicateSystems/predicate-secure
 
 ## Quick Start
 
+**[User Manual](./docs/user-manual.md)**
+
 ```typescript
 import { SecureAgent } from '@PredicateSystems/predicate-secure';
 import { Agent } from 'browser-use';
@@ -213,6 +215,30 @@ try {
 }
 ```
 
+## 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)
+
+```bash
+# 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](demo/README.md) for detailed instructions and configuration options.
+
 ## Development
 
 ```bash
@@ -241,5 +267,6 @@ MIT OR Apache-2.0
 
 ## Related
 
-- [predicate-secure (Python)](https://github.com/PredicateSystems/predicate-secure) - Python version
+- [predicate-secure (Python)](https://github.com/PredicateSystems/predicate-secure) - Python SDK with full documentation on sidecar architecture, predicate authority, and more
 - [Predicate Studio](https://predicatesystems.ai) - Cloud authorization dashboard
+- [@predicatesystems/runtime](https://www.npmjs.com/package/@predicatesystems/runtime) - Browser automation SDK with Chrome extension

demo/.env.example

@@ -0,0 +1,32 @@
+# Predicate Secure Demo Environment Variables
+# Copy to .env and customize
+
+# Predicate API key (optional - for cloud tracing to Predicate Studio)
+# Leave unset to skip cloud tracing
+# PREDICATE_API_KEY=
+
+# Browser display (false = show browser for debugging)
+BROWSER_HEADLESS=false
+
+# LLM Provider: 'ollama' (local) or 'openai' (cloud)
+LLM_PROVIDER=ollama
+
+# Ollama settings (when LLM_PROVIDER=ollama)
+OLLAMA_URL=http://localhost:11434
+LLM_MODEL_NAME=qwen2.5:7b
+
+# OpenAI settings (when LLM_PROVIDER=openai)
+# OPENAI_API_KEY=sk-...
+# LLM_MODEL_NAME=gpt-4o-mini
+
+# LLM generation parameters
+LLM_MAX_TOKENS=512
+LLM_TEMPERATURE=0.0
+
+# Demo task configuration
+DEMO_TASK_ID=example-search-task
+DEMO_START_URL=https://www.example.com
+DEMO_TASK_DESCRIPTION=Navigate to example.com and verify page loads
+DEMO_PRINCIPAL_ID=agent:demo-browser
+DEMO_TENANT_ID=tenant-demo
+DEMO_OUTPUT_DIR=demo/output

demo/README.md

@@ -0,0 +1,221 @@
+# Predicate Secure Browser Automation Demo
+
+This demo showcases the complete agent loop with:
+
+1. **Pre-execution Authorization** - Policy-based decisions before any browser action
+2. **Browser Automation** - Using PredicateBrowser (@predicatesystems/runtime) with Chrome extension
+3. **Post-execution Verification** - Local LLM (Ollama) or OpenAI for verification planning
+
+## Prerequisites
+
+### 1. Install Dependencies
+
+```bash
+# From the ts-predicate-secure directory
+npm install
+
+# The demo uses @predicatesystems/runtime which includes Playwright
+# Playwright browsers are installed automatically
+```
+
+### 2. Set Up LLM (Choose One)
+
+#### Option A: Ollama (Local - Recommended)
+
+```bash
+# Install Ollama (macOS)
+brew install ollama
+
+# Start Ollama server
+ollama serve
+
+# Pull the Qwen model (in another terminal)
+ollama pull qwen2.5:7b
+```
+
+#### Option B: OpenAI (Cloud)
+
+Set your OpenAI API key in `.env`:
+
+```bash
+LLM_PROVIDER=openai
+OPENAI_API_KEY=sk-your-key-here
+LLM_MODEL_NAME=gpt-4o-mini
+```
+
+### 3. Configure Environment
+
+```bash
+# Copy example environment file
+cp demo/.env.example demo/.env
+
+# Edit as needed
+```
+
+## Running the Demo
+
+```bash
+# From the ts-predicate-secure directory
+npx ts-node demo/secure-browser-demo.ts
+```
+
+Or with tsx (faster):
+
+```bash
+npx tsx demo/secure-browser-demo.ts
+```
+
+## What the Demo Does
+
+1. **Initializes Components**
+   - Local LLM verifier (Ollama or OpenAI)
+   - SecureAgent with policy file
+
+2. **Starts Browser**
+   - Launches Chromium via Playwright
+   - Set `BROWSER_HEADLESS=true` for headless mode
+
+3. **Executes Authorized Actions**
+   - Navigate to example.com (with authorization check)
+   - Take snapshot (verify page loaded)
+   - Find and click "More information" link
+
+4. **Verifies Each Action**
+   - LLM generates verification predicates
+   - Predicates are executed against page state
+   - Demo fails if verification fails
+
+## Demo Output
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Predicate Secure Browser Automation Demo                   │
+├────────────────────────────────────────────────────────────┤
+│ Task: Navigate to example.com and verify page loads        │
+│ Start URL: https://www.example.com                         │
+│ Principal: agent:demo-browser                              │
+└────────────────────────────────────────────────────────────┘
+
+Initializing Local LLM Verifier...
+✓ Verifier initialized
+
+Initializing Secure Agent...
+✓ SecureAgent initialized
+  Policy: demo/policies/browser_automation.yaml
+  Mode: strict (fail-closed)
+  Principal: agent:demo-browser
+
+Step 1: Initializing Browser...
+✓ Browser started
+
+Step 2: Executing Browser Task...
+
+→ Action: navigate (https://www.example.com)
+  Pre-execution: Checking authorization...
+✓ Action authorized
+  Executing action...
+✓ Action executed
+  Post-execution: Generating verification plan...
+[info] Generated 2 verifications
+    Reasoning: Verify navigation to example.com succeeded
+  Executing verifications...
+    [1] url_contains(example.com)
+        ✓ Passed
+    [2] snapshot_changed()
+        ✓ Passed
+✓ All verifications passed
+
+→ Action: snapshot (current_page)
+...
+
+✓ Task completed successfully
+
+┌────────────────────────────────────────────────────────────┐
+│ Demo completed successfully!                                │
+├────────────────────────────────────────────────────────────┤
+│ Run ID: abc123-def456-...                                  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Policy File
+
+The demo uses `policies/browser_automation.yaml` which defines:
+
+- **Allowed domains**: example.com, google.com, wikipedia.org
+- **Allowed actions**: navigate, click, snapshot, type
+- **Blocked actions**: Password fields, credit card inputs
+- **Blocked domains**: HTTP (non-HTTPS), malicious sites
+
+## Verification Predicates
+
+The LLM generates verification plans using these predicates:
+
+| Predicate | Description |
+|-----------|-------------|
+| `url_contains(substring)` | Check if URL contains substring |
+| `url_changed` | Check if URL changed after action |
+| `snapshot_changed` | Check if page content changed |
+| `element_exists(selector)` | Check if element exists in DOM |
+| `element_visible(selector)` | Check if element is visible |
+| `text_contains(substring)` | Check if page text contains substring |
+
+## Troubleshooting
+
+### Ollama not available
+
+```
+Error: Ollama not available at http://localhost:11434
+```
+
+Start Ollama: `ollama serve`
+
+### Model not found
+
+```
+Error: model 'qwen2.5:7b' not found
+```
+
+Pull the model: `ollama pull qwen2.5:7b`
+
+### Playwright browsers not installed
+
+```
+Error: Executable doesn't exist
+```
+
+Install browsers: `npx playwright install chromium`
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    SecureBrowserDemo                     │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  ┌──────────────┐    ┌──────────────┐    ┌────────────┐ │
+│  │ SecureAgent  │    │ Sentience    │    │  Verifier  │ │
+│  │  (Policy)    │    │  Browser     │    │  (LLM)     │ │
+│  └──────────────┘    └──────────────┘    └────────────┘ │
+│         │                   │                   │        │
+│         ▼                   ▼                   ▼        │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │              Authorization Loop                   │   │
+│  │  1. Check policy → 2. Execute → 3. Verify       │   │
+│  └──────────────────────────────────────────────────┘   │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+## PredicateBrowser
+
+The demo uses `PredicateBrowser` from `@predicatesystems/runtime` which:
+
+- Automatically loads the Sentience Chrome extension
+- Provides `snapshot()` for semantic element detection
+- Supports both free tier (local extension) and API tier (cloud processing)
+- Includes stealth patches to avoid bot detection
+
+## Related
+
+- [predicate-secure SDK](../README.md) - Main SDK documentation
+- [Python Demo](../../py-predicate-secure/demo/) - Python version of this demo