agent-portal-2 0.1.0

package/SAFETY_MODEL.md

@@ -0,0 +1,24 @@
+# Safety Model
+
+Agent Portal uses a policy engine to classify actions into:
+
+- `safe`
+- `low`
+- `medium`
+- `high`
+- `blocked`
+
+## Protected Actions
+
+- typing into password fields
+- billing and payment actions
+- cross-domain navigation when domain lock is enabled
+- leaving the locked tab when tab lock is enabled
+
+## Runtime Protections
+
+- duplicate browser launch prevention
+- graceful browser shutdown
+- browser disconnect detection
+- blocked and pending action queue states
+- user-facing runtime errors

package/TESTING.md

@@ -0,0 +1,35 @@
+# Testing
+
+Run the full test sweep with:
+
+```bash
+npm test
+```
+
+That command currently runs:
+
+- Python unit tests in `python/tests`
+- TypeScript builds across the workspace
+- Node tests in `tests/*.test.mjs`
+
+## Focus Areas
+
+Current automated coverage includes:
+
+- runtime action queue behavior
+- blocked action policy
+- report generation
+- runtime HTTP status endpoint
+- plugin manifest validation
+- TypeScript workspace build verification
+- VS Code extension build verification through workspace build
+
+## Recommended Manual Verification
+
+```bash
+agent-portal doctor
+agent-portal start
+agent-portal open http://localhost:3000
+agent-portal screenshot --label smoke-test
+agent-portal report
+```

package/TROUBLESHOOTING.md

@@ -0,0 +1,30 @@
+# Troubleshooting
+
+## Playwright Browser Missing
+
+Run:
+
+```bash
+npx playwright install chromium
+python -m playwright install chromium
+```
+
+## Runtime Does Not Start
+
+- verify `npm install` completed
+- run `agent-portal doctor`
+- run `npm run check`
+- inspect the runtime report directory from `agent-portal.config.json`
+
+## No VS Code Sidebar Data
+
+- open the Agent Portal repo as the current workspace
+- make sure `agent-portal start` is running
+- confirm `agentPortal.runtimeUrl` matches the local runtime
+- use `Agent Portal: Connect To Running Runtime`
+
+## Action Was Blocked
+
+- inspect the queue in the session report
+- review domain lock, tab lock, and approval thresholds
+- edit or redirect the action before retrying

package/UPGRADE_GUIDE.md

@@ -0,0 +1,288 @@
+# Upgrade Guide: v0.0.2 to v0.1.0
+
+This guide helps you upgrade from Agent Portal v0.0.2 to v0.1.0.
+
+## What's New in v0.1.0
+
+### Security Enhancements
+
+**Input Validation**
+The runtime now validates all inputs by default to prevent security issues:
+
+```python
+from agent_portal.validation import validate_url, validate_selector, validate_script
+
+# URLs are automatically validated
+result = validate_url("https://example.com")
+if not result.is_valid:
+    print(f"Validation failed: {result.errors}")
+
+# Selectors are checked for XSS patterns
+result = validate_selector("#submit-button")
+if not result.is_valid:
+    print(f"Unsafe selector: {result.errors}")
+
+# Scripts are validated for dangerous operations
+result = validate_script("document.querySelector('div')")
+if not result.is_valid:
+    print(f"Unsafe script: {result.errors}")
+```
+
+**Rate Limiting**
+The server now includes rate limiting to prevent abuse:
+
+```python
+from agent_portal import RateLimiter, RateLimitConfig
+
+# Configure rate limits
+config = RateLimitConfig(
+    requests_per_minute=60,
+    requests_per_hour=1000,
+    burst_limit=10,
+    burst_window_seconds=1.0
+)
+
+limiter = RateLimiter(config)
+
+# Check if a request is allowed
+allowed, error = limiter.check_rate_limit("client-123")
+if not allowed:
+    print(f"Rate limited: {error}")
+```
+
+**Action Throttling**
+Specific actions have stricter limits:
+
+```python
+from agent_portal import ActionThrottler
+
+throttler = ActionThrottler()
+
+# Execute actions are limited to 5 per minute
+allowed, error = throttler.check_action_allowed("execute", "client-123")
+if not allowed:
+    print(f"Action throttled: {error}")
+```
+
+### Observability
+
+**Metrics Collection**
+Track runtime operations with built-in metrics:
+
+```python
+from agent_portal import MetricsCollector, get_metrics
+
+# Get the global metrics collector
+metrics = get_metrics()
+
+# Track actions
+metrics.increment("actions.completed", tags={"action": "click"})
+metrics.increment("actions.failed", tags={"action": "navigate"})
+
+# Track browser operations
+metrics.set_gauge("runtime.browser_connected", 1.0)
+metrics.increment("browser.screenshots")
+
+# Time operations
+with metrics.start_timer("operation.duration", tags={"type": "navigate"}):
+    # Your operation here
+    pass
+
+# View statistics
+print(metrics.get_timer_stats("operation.duration"))
+print(metrics.get_histogram("action.sizes"))
+```
+
+**Export Metrics**
+Export metrics to JSON files for analysis:
+
+```python
+from pathlib import Path
+
+metrics.export_to_file(Path("metrics.json"))
+```
+
+## Migration Steps
+
+### 1. Update Dependencies
+
+```bash
+pip install --upgrade agent-portal
+```
+
+### 2. Review Rate Limits
+
+The default rate limits are:
+- 60 requests per minute
+- 1000 requests per hour
+- 10 burst requests per second
+
+Customize these in your server configuration if needed:
+
+```python
+from agent_portal.server import build_server
+from agent_portal import RateLimiter, RateLimitConfig
+
+# Custom rate limits
+rate_config = RateLimitConfig(
+    requests_per_minute=120,
+    requests_per_hour=5000,
+    burst_limit=20
+)
+
+# Note: You'll need to integrate this with your server setup
+# See the documentation for full integration details
+```
+
+### 3. Validate Your Code
+
+The new validation may reject previously accepted inputs. Test your workflows:
+
+```python
+# Test your URLs
+from agent_portal.validation import validate_url
+
+test_urls = [
+    "https://your-app.com",
+    "http://localhost:3000",
+]
+
+for url in test_urls:
+    result = validate_url(url)
+    if not result.is_valid:
+        print(f"URL validation failed for {url}: {result.errors}")
+```
+
+### 4. Monitor Metrics
+
+Enable metrics monitoring in your workflows:
+
+```python
+from agent_portal import get_metrics
+
+metrics = get_metrics()
+
+# Check key metrics
+print(f"Total actions: {metrics.get_counter('actions.total')}")
+print(f"Completed: {metrics.get_counter('actions.completed')}")
+print(f"Failed: {metrics.get_counter('actions.failed')}")
+print(f"Browser connected: {metrics.get_gauge('runtime.browser_connected')}")
+```
+
+## Breaking Changes
+
+**None** - This release maintains full backward compatibility.
+
+All existing workflows should continue to work without modification.
+
+## New Configuration Options
+
+### Rate Limiting Configuration
+
+Add to your `agent-portal.config.json`:
+
+```json
+{
+  "rateLimiting": {
+    "enabled": true,
+    "requestsPerMinute": 60,
+    "requestsPerHour": 1000,
+    "burstLimit": 10,
+    "burstWindowSeconds": 1.0
+  }
+}
+```
+
+### Metrics Configuration
+
+```json
+{
+  "metrics": {
+    "enabled": true,
+    "maxSamples": 10000,
+    "exportPath": "workspaces/runtime/metrics"
+  }
+}
+```
+
+## Security Considerations
+
+### URL Validation
+The runtime now blocks:
+- JavaScript URLs (`javascript:`)
+- Data URLs (`data:`)
+- File URLs (`file:`)
+- VBScript URLs (`vbscript:`)
+
+### Selector Validation
+Selectors containing the following patterns are rejected:
+- `<script`
+- `javascript:`
+- `onerror=`, `onload=`, `onclick=`
+- `fromCharCode`
+- `eval(`
+
+### Script Validation
+Scripts with these operations are flagged:
+- `document.cookie`
+- `localStorage`, `sessionStorage`
+- `window.location`
+- `eval()`, `Function()`
+- `document.write`
+- `XMLHttpRequest`, `fetch()`
+
+## Testing Your Upgrade
+
+Run the test suite to ensure everything works:
+
+```bash
+# Run all tests
+npm test
+
+# Run Python tests only
+python -m unittest discover -s python/tests -v
+
+# Run specific test modules
+python -m unittest tests.test_validation -v
+python -m unittest tests.test_rate_limit -v
+python -m unittest tests.test_metrics -v
+```
+
+## Troubleshooting
+
+### Rate Limit Errors
+
+If you see rate limit errors:
+1. Increase limits in configuration
+2. Implement exponential backoff in your client
+3. Use batch operations when possible
+
+### Validation Errors
+
+If validation fails:
+1. Review the error messages
+2. Update your inputs to meet validation requirements
+3. Use `sanitize_text()` to clean inputs if needed
+
+### Metrics Not Working
+
+If metrics aren't being collected:
+1. Check that the metrics module is imported
+2. Ensure you're using the global collector via `get_metrics()`
+3. Verify no exceptions are being swallowed
+
+## Getting Help
+
+- 📖 **Documentation**: See the full [README.md](README.md)
+- 🐛 **Issues**: Report bugs at [GitHub Issues](https://github.com/magnexis/agent-portal/issues)
+- 💬 **Discussions**: Ask questions in [GitHub Discussions](https://github.com/magnexis/agent-portal/discussions)
+
+## What's Next
+
+Future releases will include:
+- Advanced vision core for page understanding
+- Multi-agent coordination
+- Desktop application control
+- Enhanced reporting capabilities
+
+Stay tuned for more updates!

package/VS_CODE_EXTENSION.md

@@ -0,0 +1,47 @@
+# VS Code Extension
+
+The VS Code extension lives in `apps/vscode-extension`.
+
+Official extension link:
+
+- [Agent Portal on the Visual Studio Marketplace](https://marketplace.visualstudio.com/manage/publishers/magnificent-language/extensions/agent-portal/hub)
+
+## Features
+
+- sidebar control center
+- runtime start and stop commands
+- restart runtime command
+- connect directly to the Python runtime HTTP server
+- pending action queue preview
+- approve and reject controls
+- local development server detection for:
+  - `localhost:3000`
+  - `localhost:5173`
+  - `localhost:8080`
+  - `localhost:8000`
+  - `localhost:5000`
+
+## Primary Commands
+
+- `Agent Portal: Start Runtime`
+- `Agent Portal: Stop Runtime`
+- `Agent Portal: Restart Runtime`
+- `Agent Portal: Open Current Project`
+- `Agent Portal: Run Agent`
+- `Agent Portal: Pause Agent`
+- `Agent Portal: Resume Agent`
+- `Agent Portal: Stop Agent`
+- `Agent Portal: Approve Next Action`
+- `Agent Portal: Reject Next Action`
+- `Agent Portal: Generate Report`
+- `Agent Portal: Open Documentation`
+
+## Runtime Relationship
+
+The extension is the developer-facing control panel.
+The Python `agent_portal` package owns the local runtime, Playwright session, and API surfaces.
+
+## Settings
+
+- `agentPortal.runtimeUrl`
+- `agentPortal.preferredLocalDevPort`

package/agent-portal.config.json

@@ -0,0 +1,20 @@
+{
+  "runtime_host": "127.0.0.1",
+  "runtime_port": 8765,
+  "screenshot_directory": "workspaces/runtime/screenshots",
+  "report_directory": "workspaces/runtime/reports",
+  "default_browser": "chromium",
+  "action_mode": "assisted",
+  "approval_policy": "medium",
+  "allowed_domains": [],
+  "blocked_domains": [],
+  "enabled_plugins": [
+    "agent-portal-vscode",
+    "agent-portal-browser"
+  ],
+  "log_level": "INFO",
+  "retention_days": 14,
+  "sensitive_screenshots_enabled": false,
+  "safe_mode": true,
+  "api_token": null
+}

package/apps/desktop/fixtures/local-workflow.html

@@ -0,0 +1,151 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Agent Portal Local Workflow</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #05070c;
+        --panel: #0f1623;
+        --line: rgba(255, 255, 255, 0.1);
+        --text: #eef3ff;
+        --muted: #9cb2d1;
+        --blue: #3cc8ff;
+        --orange: #ff9a1f;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background:
+          radial-gradient(circle at top left, rgba(60, 200, 255, 0.2), transparent 28%),
+          radial-gradient(circle at top right, rgba(255, 154, 31, 0.2), transparent 30%),
+          linear-gradient(180deg, #070b12, var(--bg));
+        color: var(--text);
+        font-family: "Segoe UI", system-ui, sans-serif;
+      }
+
+      .panel {
+        width: min(92vw, 720px);
+        padding: 40px;
+        border: 1px solid var(--line);
+        border-radius: 28px;
+        background: linear-gradient(180deg, rgba(15, 22, 35, 0.96), rgba(7, 11, 18, 0.98));
+        box-shadow: 0 30px 80px rgba(0, 0, 0, 0.45);
+      }
+
+      .eyebrow {
+        font-size: 12px;
+        letter-spacing: 0.24em;
+        text-transform: uppercase;
+        color: var(--blue);
+      }
+
+      h1 {
+        margin: 12px 0 8px;
+        font-size: clamp(2rem, 5vw, 3.4rem);
+      }
+
+      p {
+        margin: 0 0 24px;
+        color: var(--muted);
+        line-height: 1.6;
+      }
+
+      form {
+        display: grid;
+        gap: 14px;
+      }
+
+      label {
+        font-size: 0.95rem;
+      }
+
+      input {
+        width: 100%;
+        padding: 14px 16px;
+        border: 1px solid rgba(60, 200, 255, 0.32);
+        border-radius: 14px;
+        background: rgba(7, 11, 18, 0.85);
+        color: var(--text);
+        font: inherit;
+      }
+
+      button {
+        padding: 14px 18px;
+        border: 0;
+        border-radius: 14px;
+        background: linear-gradient(90deg, var(--blue), var(--orange));
+        color: #061019;
+        font: inherit;
+        font-weight: 700;
+        cursor: pointer;
+      }
+
+      .result {
+        margin-top: 20px;
+        padding: 16px;
+        border-radius: 16px;
+        border: 1px solid rgba(255, 154, 31, 0.24);
+        background: rgba(255, 154, 31, 0.08);
+      }
+
+      .spacer {
+        height: 70vh;
+      }
+
+      .evidence {
+        margin-top: 24px;
+        padding: 20px;
+        border-radius: 18px;
+        border: 1px solid rgba(60, 200, 255, 0.24);
+        background: rgba(60, 200, 255, 0.08);
+      }
+    </style>
+  </head>
+  <body>
+    <main class="panel">
+      <div class="eyebrow">Local Proving Ground</div>
+      <h1>See, Act, Record</h1>
+      <p>
+        This local page exists to prove the Agent Portal browser loop against a
+        controlled app inside the repository.
+      </p>
+      <form id="workflow-form">
+        <label for="name">Agent Name</label>
+        <input id="name" name="name" type="text" placeholder="Portal Runner" />
+        <button id="generate-report" type="submit">Generate Result</button>
+      </form>
+      <div id="result" class="result" aria-live="polite">
+        Waiting for the agent to complete the workflow.
+      </div>
+      <div class="spacer" aria-hidden="true"></div>
+      <section id="evidence-panel" class="evidence">
+        <strong>Evidence Panel</strong>
+        <p>
+          If the agent reached this section, scrolling worked as part of the
+          browser automation flow.
+        </p>
+      </section>
+    </main>
+    <script>
+      const form = document.getElementById("workflow-form");
+      const result = document.getElementById("result");
+      const input = document.getElementById("name");
+
+      form.addEventListener("submit", (event) => {
+        event.preventDefault();
+        const value = input.value.trim() || "Unknown Agent";
+        result.textContent = `Workflow completed for ${value}. Screenshot and report are ready.`;
+      });
+    </script>
+  </body>
+  </html>

package/apps/desktop/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@agent-portal/desktop",
+  "version": "0.0.2",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "npm run build --workspace @agent-portal/core && tsc -p tsconfig.json && node dist/main.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "package": "npm run build && node ../../scripts/package_desktop.mjs"
+  },
+  "dependencies": {
+    "@agent-portal/core": "0.0.2"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2"
+  }
+}