predicate-claw 0.1.0

package/examples/policy/workspace-isolation.yaml

@@ -0,0 +1,51 @@
+# Workspace Isolation Policy
+# Restricts all file operations to a specific project directory.
+#
+# Usage:
+#   1. Update WORKSPACE_ROOT to your project path
+#   2. Add any additional allowed paths to the allowlist
+
+version: 1
+
+defaults:
+  effect: deny
+
+rules:
+  # Allow reads within the workspace
+  - id: allow_workspace_reads
+    effect: allow
+    action: fs.read
+    resource: ./workspace/**
+
+  # Allow writes within the workspace
+  - id: allow_workspace_writes
+    effect: allow
+    action: fs.write
+    resource: ./workspace/**
+
+  # Allow reading package manifests (for dependency resolution)
+  - id: allow_package_manifests
+    effect: allow
+    action: fs.read
+    resource:
+      - ./package.json
+      - ./package-lock.json
+      - ./yarn.lock
+      - ./pnpm-lock.yaml
+      - ./Cargo.toml
+      - ./Cargo.lock
+      - ./go.mod
+      - ./go.sum
+      - ./requirements.txt
+      - ./pyproject.toml
+
+  # Deny all paths outside workspace (explicit for clarity)
+  - id: deny_outside_workspace
+    effect: deny
+    action: fs.*
+    resource: /**
+
+metadata:
+  name: Workspace Isolation
+  description: Restrict file operations to project directory
+  version: 1.0.0

package/examples/runtime_registry_example.py

@@ -0,0 +1,75 @@
+"""Example wiring for OpenClawRuntimeIntegrator with a mock registry."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from openclaw_predicate_provider.integrations import OpenClawRuntimeIntegrator
+from openclaw_predicate_provider.openclaw_hooks import HookEnvelope, OpenClawHooks
+
+
+class MockRegistry:
+    def __init__(self) -> None:
+        self._handlers = {
+            "cmd.run": self._cmd_run,
+            "fs.readFile": self._fs_read,
+            "http.request": self._http_request,
+        }
+
+    async def _cmd_run(self, args: dict[str, Any]) -> dict[str, Any]:
+        return {"tool": "cmd.run", "args": args}
+
+    async def _fs_read(self, args: dict[str, Any]) -> dict[str, Any]:
+        return {"tool": "fs.readFile", "args": args}
+
+    async def _http_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        return {"tool": "http.request", "args": args}
+
+    def get(self, tool_name: str):
+        return self._handlers[tool_name]
+
+    def set(self, tool_name: str, handler) -> None:
+        self._handlers[tool_name] = handler
+
+    async def invoke(self, tool_name: str, args: dict[str, Any]) -> dict[str, Any]:
+        return await self._handlers[tool_name](args)
+
+
+def build_context(tool_name: str, args: dict[str, Any]) -> HookEnvelope:
+    return HookEnvelope(
+        tool_name=tool_name,
+        args=args,
+        session_id="demo-session",
+        source="trusted_ui",
+        tenant_id="demo-tenant",
+    )
+
+
+async def main() -> None:
+    # In real OpenClaw integration this uses GuardedProvider+ToolAdapter hooks.
+    class PassThroughHooks:
+        async def on_cmd_run(self, envelope, execute):
+            return await execute(envelope.args)
+
+        async def on_fs_read(self, envelope, execute):
+            return await execute(envelope.args)
+
+        async def on_http_request(self, envelope, execute):
+            return await execute(envelope.args)
+
+    hooks = PassThroughHooks()
+    integrator = OpenClawRuntimeIntegrator(
+        hooks=hooks,  # type: ignore[arg-type]
+        context_builder=build_context,
+    )
+    registry = MockRegistry()
+    integrator.register(registry)
+
+    print(await registry.invoke("cmd.run", {"command": "echo hello"}))
+    print(await registry.invoke("fs.readFile", {"path": "./README.md"}))
+    print(await registry.invoke("http.request", {"url": "https://example.com"}))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "predicate-claw",
+  "version": "0.1.0",
+  "description": "TypeScript OpenClaw security provider with Predicate Authority pre-execution checks.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:demo": "vitest run tests/hack-vs-fix-demo.test.ts",
+    "test:ci": "npm run typecheck && npm test"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "(MIT OR Apache-2.0)",
+  "type": "module",
+  "dependencies": {
+    "@predicatesystems/authority": "^0.3.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "openclaw": "^2026.2.19-2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openclaw-predicate-provider"
+version = "0.1.0"
+description = "OpenClaw provider for deterministic Predicate Authority enforcement."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT OR Apache-2.0" }
+authors = [{ name = "Predicate Systems" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.7.0",
+  "httpx>=0.27.0",
+]
+
+[project.scripts]
+openclaw-predicate-provider = "openclaw_predicate_provider.cli:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["openclaw_predicate_provider*"]
+
+[tool.setuptools.package-data]
+openclaw_predicate_provider = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

package/src/adapter.ts

@@ -0,0 +1,45 @@
+import type { GuardedProvider } from "./provider.js";
+
+export interface ToolRunArgs {
+  args: Record<string, unknown>;
+  context: Record<string, unknown>;
+  execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+export class ToolAdapter {
+  constructor(private readonly guard: Pick<GuardedProvider, "guardOrThrow">) {}
+
+  async run(params: ToolRunArgs & { action: string; resource: string }) {
+    await this.guard.guardOrThrow({
+      action: params.action,
+      resource: params.resource,
+      args: params.args,
+      context: params.context,
+    });
+    return params.execute(params.args);
+  }
+
+  async runShell(params: ToolRunArgs) {
+    return this.run({
+      ...params,
+      action: "shell.execute",
+      resource: String(params.args.command ?? ""),
+    });
+  }
+
+  async readFile(params: ToolRunArgs) {
+    return this.run({
+      ...params,
+      action: "fs.read",
+      resource: String(params.args.path ?? ""),
+    });
+  }
+
+  async httpRequest(params: ToolRunArgs) {
+    return this.run({
+      ...params,
+      action: "net.http",
+      resource: String(params.args.url ?? ""),
+    });
+  }
+}

package/src/authority-client.ts

@@ -0,0 +1,50 @@
+import {
+  AuthorityClient,
+  type AuthorizationRequest,
+} from "@predicatesystems/authority";
+import type { ProviderConfig } from "./config.js";
+
+export interface AuthorityDecision {
+  allow: boolean;
+  reason?: string;
+  mandateId?: string;
+}
+
+export interface AuthorityAdapter {
+  authorize(request: AuthorizationRequest): Promise<AuthorityDecision>;
+}
+
+interface SdkDecision {
+  allowed: boolean;
+  reason?: string;
+  mandate_id?: string | null;
+}
+
+interface SdkLike {
+  authorize(request: AuthorizationRequest): Promise<SdkDecision>;
+}
+
+export function createAuthorityAdapter(client: SdkLike): AuthorityAdapter {
+  return {
+    async authorize(request: AuthorizationRequest): Promise<AuthorityDecision> {
+      const decision = await client.authorize(request);
+      return {
+        allow: decision.allowed,
+        reason: decision.reason,
+        mandateId: decision.mandate_id ?? undefined,
+      };
+    },
+  };
+}
+
+export function createDefaultAuthorityAdapter(
+  config: ProviderConfig,
+): AuthorityAdapter {
+  const sdkClient = new AuthorityClient({
+    baseUrl: config.baseUrl,
+    timeoutMs: config.timeoutMs,
+    maxRetries: config.maxRetries,
+    backoffInitialMs: config.backoffInitialMs,
+  });
+  return createAuthorityAdapter(sdkClient);
+}

package/src/circuit-breaker.ts

@@ -0,0 +1,245 @@
+/**
+ * Circuit breaker for sidecar outage resilience.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Too many failures, requests fail fast without calling sidecar
+ * - HALF_OPEN: Testing if sidecar has recovered
+ */
+
+export type CircuitState = "closed" | "open" | "half_open";
+
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening the circuit */
+  failureThreshold: number;
+  /** Time in ms before attempting recovery (half-open state) */
+  resetTimeoutMs: number;
+  /** Number of successful calls in half-open to close circuit */
+  successThreshold: number;
+  /** Optional callback when state changes */
+  onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+
+export const defaultCircuitBreakerConfig: CircuitBreakerConfig = {
+  failureThreshold: 5,
+  resetTimeoutMs: 30_000,
+  successThreshold: 2,
+};
+
+export interface CircuitBreakerMetrics {
+  state: CircuitState;
+  failureCount: number;
+  successCount: number;
+  lastFailureTime: number | null;
+  totalFailures: number;
+  totalSuccesses: number;
+  totalRejections: number;
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = "closed";
+  private failureCount = 0;
+  private successCount = 0;
+  private lastFailureTime: number | null = null;
+  private totalFailures = 0;
+  private totalSuccesses = 0;
+  private totalRejections = 0;
+
+  constructor(private readonly config: CircuitBreakerConfig) {}
+
+  getMetrics(): CircuitBreakerMetrics {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      successCount: this.successCount,
+      lastFailureTime: this.lastFailureTime,
+      totalFailures: this.totalFailures,
+      totalSuccesses: this.totalSuccesses,
+      totalRejections: this.totalRejections,
+    };
+  }
+
+  getState(): CircuitState {
+    return this.state;
+  }
+
+  /**
+   * Check if request should be allowed through.
+   * Returns true if allowed, false if circuit is open.
+   */
+  allowRequest(): boolean {
+    if (this.state === "closed") {
+      return true;
+    }
+
+    if (this.state === "open") {
+      const now = Date.now();
+      if (
+        this.lastFailureTime !== null &&
+        now - this.lastFailureTime >= this.config.resetTimeoutMs
+      ) {
+        this.transitionTo("half_open");
+        return true;
+      }
+      this.totalRejections++;
+      return false;
+    }
+
+    // half_open: allow limited requests to test recovery
+    return true;
+  }
+
+  /**
+   * Record a successful call.
+   */
+  recordSuccess(): void {
+    this.totalSuccesses++;
+
+    if (this.state === "half_open") {
+      this.successCount++;
+      if (this.successCount >= this.config.successThreshold) {
+        this.transitionTo("closed");
+      }
+    } else if (this.state === "closed") {
+      // Reset failure count on success
+      this.failureCount = 0;
+    }
+  }
+
+  /**
+   * Record a failed call.
+   */
+  recordFailure(): void {
+    this.totalFailures++;
+    this.lastFailureTime = Date.now();
+
+    if (this.state === "half_open") {
+      // Any failure in half-open reopens the circuit
+      this.transitionTo("open");
+      return;
+    }
+
+    if (this.state === "closed") {
+      this.failureCount++;
+      if (this.failureCount >= this.config.failureThreshold) {
+        this.transitionTo("open");
+      }
+    }
+  }
+
+  /**
+   * Force reset to closed state (e.g., for testing or manual recovery).
+   */
+  reset(): void {
+    this.transitionTo("closed");
+  }
+
+  private transitionTo(newState: CircuitState): void {
+    if (this.state === newState) return;
+
+    const oldState = this.state;
+    this.state = newState;
+
+    // Reset counters on state change
+    if (newState === "closed") {
+      this.failureCount = 0;
+      this.successCount = 0;
+    } else if (newState === "half_open") {
+      this.successCount = 0;
+    } else if (newState === "open") {
+      this.successCount = 0;
+    }
+
+    this.config.onStateChange?.(oldState, newState);
+  }
+}
+
+/**
+ * Exponential backoff calculator with jitter.
+ */
+export interface BackoffConfig {
+  initialMs: number;
+  maxMs: number;
+  multiplier: number;
+  jitterFactor: number;
+}
+
+export const defaultBackoffConfig: BackoffConfig = {
+  initialMs: 100,
+  maxMs: 10_000,
+  multiplier: 2,
+  jitterFactor: 0.1,
+};
+
+export function calculateBackoff(
+  attempt: number,
+  config: BackoffConfig = defaultBackoffConfig,
+): number {
+  const base = Math.min(
+    config.initialMs * Math.pow(config.multiplier, attempt),
+    config.maxMs,
+  );
+  const jitter = base * config.jitterFactor * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(base + jitter));
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Wrap an async function with circuit breaker and retry logic.
+ */
+export async function withCircuitBreaker<T>(
+  breaker: CircuitBreaker,
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoffConfig?: BackoffConfig;
+    isFailure?: (error: unknown) => boolean;
+  },
+): Promise<T> {
+  const maxRetries = options?.maxRetries ?? 0;
+  const backoffConfig = options?.backoffConfig ?? defaultBackoffConfig;
+  const isFailure = options?.isFailure ?? (() => true);
+
+  if (!breaker.allowRequest()) {
+    throw new CircuitOpenError("Circuit breaker is open");
+  }
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await fn();
+      breaker.recordSuccess();
+      return result;
+    } catch (error) {
+      lastError = error;
+
+      if (!isFailure(error)) {
+        // Not a circuit-breaker-relevant failure (e.g., business logic error)
+        throw error;
+      }
+
+      breaker.recordFailure();
+
+      if (attempt < maxRetries && breaker.allowRequest()) {
+        const delay = calculateBackoff(attempt, backoffConfig);
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+export class CircuitOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CircuitOpenError";
+  }
+}

package/src/config.ts

@@ -0,0 +1,15 @@
+export interface ProviderConfig {
+  baseUrl: string;
+  timeoutMs: number;
+  maxRetries: number;
+  backoffInitialMs: number;
+  failClosed: boolean;
+}
+
+export const defaultProviderConfig: ProviderConfig = {
+  baseUrl: "http://127.0.0.1:8787",
+  timeoutMs: 300,
+  maxRetries: 0,
+  backoffInitialMs: 100,
+  failClosed: true,
+};