predicate-claw 0.1.0

package/dist/src/authority-client.js

@@ -0,0 +1,22 @@
+import { AuthorityClient, } from "@predicatesystems/authority";
+export function createAuthorityAdapter(client) {
+    return {
+        async authorize(request) {
+            const decision = await client.authorize(request);
+            return {
+                allow: decision.allowed,
+                reason: decision.reason,
+                mandateId: decision.mandate_id ?? undefined,
+            };
+        },
+    };
+}
+export function createDefaultAuthorityAdapter(config) {
+    const sdkClient = new AuthorityClient({
+        baseUrl: config.baseUrl,
+        timeoutMs: config.timeoutMs,
+        maxRetries: config.maxRetries,
+        backoffInitialMs: config.backoffInitialMs,
+    });
+    return createAuthorityAdapter(sdkClient);
+}

package/dist/src/circuit-breaker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 declare const defaultCircuitBreakerConfig: CircuitBreakerConfig;
+export interface CircuitBreakerMetrics {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime: number | null;
+    totalFailures: number;
+    totalSuccesses: number;
+    totalRejections: number;
+}
+export declare class CircuitBreaker {
+    private readonly config;
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private totalFailures;
+    private totalSuccesses;
+    private totalRejections;
+    constructor(config: CircuitBreakerConfig);
+    getMetrics(): CircuitBreakerMetrics;
+    getState(): CircuitState;
+    /**
+     * Check if request should be allowed through.
+     * Returns true if allowed, false if circuit is open.
+     */
+    allowRequest(): boolean;
+    /**
+     * Record a successful call.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed call.
+     */
+    recordFailure(): void;
+    /**
+     * Force reset to closed state (e.g., for testing or manual recovery).
+     */
+    reset(): void;
+    private transitionTo;
+}
+/**
+ * Exponential backoff calculator with jitter.
+ */
+export interface BackoffConfig {
+    initialMs: number;
+    maxMs: number;
+    multiplier: number;
+    jitterFactor: number;
+}
+export declare const defaultBackoffConfig: BackoffConfig;
+export declare function calculateBackoff(attempt: number, config?: BackoffConfig): number;
+/**
+ * Sleep for a given number of milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Wrap an async function with circuit breaker and retry logic.
+ */
+export declare function withCircuitBreaker<T>(breaker: CircuitBreaker, fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    backoffConfig?: BackoffConfig;
+    isFailure?: (error: unknown) => boolean;
+}): Promise<T>;
+export declare class CircuitOpenError extends Error {
+    constructor(message: string);
+}

package/dist/src/circuit-breaker.js

@@ -0,0 +1,174 @@
+/**
+ * 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 const defaultCircuitBreakerConfig = {
+    failureThreshold: 5,
+    resetTimeoutMs: 30_000,
+    successThreshold: 2,
+};
+export class CircuitBreaker {
+    config;
+    state = "closed";
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime = null;
+    totalFailures = 0;
+    totalSuccesses = 0;
+    totalRejections = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    getMetrics() {
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            successCount: this.successCount,
+            lastFailureTime: this.lastFailureTime,
+            totalFailures: this.totalFailures,
+            totalSuccesses: this.totalSuccesses,
+            totalRejections: this.totalRejections,
+        };
+    }
+    getState() {
+        return this.state;
+    }
+    /**
+     * Check if request should be allowed through.
+     * Returns true if allowed, false if circuit is open.
+     */
+    allowRequest() {
+        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() {
+        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() {
+        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() {
+        this.transitionTo("closed");
+    }
+    transitionTo(newState) {
+        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);
+    }
+}
+export const defaultBackoffConfig = {
+    initialMs: 100,
+    maxMs: 10_000,
+    multiplier: 2,
+    jitterFactor: 0.1,
+};
+export function calculateBackoff(attempt, config = defaultBackoffConfig) {
+    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) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wrap an async function with circuit breaker and retry logic.
+ */
+export async function withCircuitBreaker(breaker, fn, options) {
+    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;
+    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) {
+        super(message);
+        this.name = "CircuitOpenError";
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,8 @@
+export interface ProviderConfig {
+    baseUrl: string;
+    timeoutMs: number;
+    maxRetries: number;
+    backoffInitialMs: number;
+    failClosed: boolean;
+}
+export declare const defaultProviderConfig: ProviderConfig;

package/dist/src/config.js

@@ -0,0 +1,7 @@
+export const defaultProviderConfig = {
+    baseUrl: "http://127.0.0.1:8787",
+    timeoutMs: 300,
+    maxRetries: 0,
+    backoffInitialMs: 100,
+    failClosed: true,
+};

package/dist/src/control-plane-sync.d.ts

@@ -0,0 +1,57 @@
+export interface ControlPlaneSyncConfig {
+    baseUrl: string;
+    tenantId: string;
+    timeoutMs?: number;
+}
+export interface PolicySyncSnapshot {
+    version: string;
+    cursor: string;
+    rules: unknown[];
+}
+export interface RevocationSyncSnapshot {
+    version: string;
+    cursor: string;
+    revoked: unknown[];
+}
+export interface ControlPlaneSyncStatus {
+    policyVersion: string;
+    revocationVersion: string;
+    pinnedPolicyVersion?: string;
+    policyVersionMismatch: boolean;
+    stale: boolean;
+    syncAgeMs: number;
+    lastSyncedAtMs: number;
+}
+export interface ControlPlaneSyncStatusTrackerOptions {
+    pinnedPolicyVersion?: string;
+    staleAfterMs?: number;
+    onStatus?: (status: ControlPlaneSyncStatus) => void;
+}
+export declare class ControlPlaneSyncClient {
+    private readonly baseUrl;
+    private readonly tenantId;
+    private readonly timeoutMs;
+    constructor(config: ControlPlaneSyncConfig);
+    pullPolicySnapshot(cursor?: string): Promise<PolicySyncSnapshot>;
+    pullRevocationSnapshot(cursor?: string): Promise<RevocationSyncSnapshot>;
+    private fetchWithTimeout;
+}
+export declare class ControlPlaneSyncStatusTracker {
+    private readonly pinnedPolicyVersion?;
+    private readonly staleAfterMs;
+    private readonly onStatus?;
+    private latest?;
+    constructor(options?: ControlPlaneSyncStatusTrackerOptions);
+    recordSync(snapshot: {
+        policy: PolicySyncSnapshot;
+        revocations: RevocationSyncSnapshot;
+    }, nowMs?: number): ControlPlaneSyncStatus;
+    snapshot(nowMs?: number): ControlPlaneSyncStatus;
+}
+export declare function syncControlPlaneState(client: ControlPlaneSyncClient, cursors?: {
+    policyCursor?: string;
+    revocationCursor?: string;
+}): Promise<{
+    policy: PolicySyncSnapshot;
+    revocations: RevocationSyncSnapshot;
+}>;

package/dist/src/control-plane-sync.js

@@ -0,0 +1,99 @@
+export class ControlPlaneSyncClient {
+    baseUrl;
+    tenantId;
+    timeoutMs;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.tenantId = config.tenantId;
+        this.timeoutMs = config.timeoutMs ?? 3000;
+    }
+    async pullPolicySnapshot(cursor) {
+        const url = new URL(`${this.baseUrl}/v1/policy/sync`);
+        url.searchParams.set("tenant_id", this.tenantId);
+        if (cursor) {
+            url.searchParams.set("cursor", cursor);
+        }
+        const response = await this.fetchWithTimeout(url.toString());
+        if (!response.ok) {
+            throw new Error(`policy sync failed: ${response.status}`);
+        }
+        return (await response.json());
+    }
+    async pullRevocationSnapshot(cursor) {
+        const url = new URL(`${this.baseUrl}/v1/revocations/sync`);
+        url.searchParams.set("tenant_id", this.tenantId);
+        if (cursor) {
+            url.searchParams.set("cursor", cursor);
+        }
+        const response = await this.fetchWithTimeout(url.toString());
+        if (!response.ok) {
+            throw new Error(`revocation sync failed: ${response.status}`);
+        }
+        return (await response.json());
+    }
+    async fetchWithTimeout(input) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await fetch(input, { signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export class ControlPlaneSyncStatusTracker {
+    pinnedPolicyVersion;
+    staleAfterMs;
+    onStatus;
+    latest;
+    constructor(options) {
+        this.pinnedPolicyVersion = options?.pinnedPolicyVersion;
+        this.staleAfterMs = options?.staleAfterMs ?? 300000;
+        this.onStatus = options?.onStatus;
+    }
+    recordSync(snapshot, nowMs = Date.now()) {
+        this.latest = {
+            policyVersion: snapshot.policy.version,
+            revocationVersion: snapshot.revocations.version,
+            lastSyncedAtMs: nowMs,
+        };
+        const status = this.snapshot(nowMs);
+        this.onStatus?.(status);
+        return status;
+    }
+    snapshot(nowMs = Date.now()) {
+        if (!this.latest) {
+            return {
+                policyVersion: "unknown",
+                revocationVersion: "unknown",
+                pinnedPolicyVersion: this.pinnedPolicyVersion,
+                policyVersionMismatch: false,
+                stale: true,
+                syncAgeMs: Number.POSITIVE_INFINITY,
+                lastSyncedAtMs: 0,
+            };
+        }
+        const syncAgeMs = Math.max(0, nowMs - this.latest.lastSyncedAtMs);
+        const policyVersionMismatch = typeof this.pinnedPolicyVersion === "string" &&
+            this.pinnedPolicyVersion.length > 0
+            ? this.latest.policyVersion !== this.pinnedPolicyVersion
+            : false;
+        return {
+            policyVersion: this.latest.policyVersion,
+            revocationVersion: this.latest.revocationVersion,
+            pinnedPolicyVersion: this.pinnedPolicyVersion,
+            policyVersionMismatch,
+            stale: syncAgeMs > this.staleAfterMs,
+            syncAgeMs,
+            lastSyncedAtMs: this.latest.lastSyncedAtMs,
+        };
+    }
+}
+export async function syncControlPlaneState(client, cursors) {
+    const [policy, revocations] = await Promise.all([
+        client.pullPolicySnapshot(cursors?.policyCursor),
+        client.pullRevocationSnapshot(cursors?.revocationCursor),
+    ]);
+    return { policy, revocations };
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class GuardError extends Error {
+}
+export declare class ActionDeniedError extends GuardError {
+}
+export declare class SidecarUnavailableError extends GuardError {
+}

package/dist/src/errors.js

@@ -0,0 +1,6 @@
+export class GuardError extends Error {
+}
+export class ActionDeniedError extends GuardError {
+}
+export class SidecarUnavailableError extends GuardError {
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./adapter.js";
+export * from "./authority-client.js";
+export * from "./circuit-breaker.js";
+export * from "./config.js";
+export * from "./control-plane-sync.js";
+export * from "./errors.js";
+export * from "./non-web-evidence.js";
+export * from "./web-evidence.js";
+export * from "./openclaw-hooks.js";
+export * from "./openclaw-plugin-api.js";
+export * from "./provider.js";
+export * from "./runtime-integration.js";

package/dist/src/index.js

@@ -0,0 +1,12 @@
+export * from "./adapter.js";
+export * from "./authority-client.js";
+export * from "./circuit-breaker.js";
+export * from "./config.js";
+export * from "./control-plane-sync.js";
+export * from "./errors.js";
+export * from "./non-web-evidence.js";
+export * from "./web-evidence.js";
+export * from "./openclaw-hooks.js";
+export * from "./openclaw-plugin-api.js";
+export * from "./provider.js";
+export * from "./runtime-integration.js";

package/dist/src/non-web-evidence.d.ts

@@ -0,0 +1,46 @@
+import { type DesktopAccessibilityEvidenceProvider, type DesktopAccessibilitySnapshot, type StateEvidence, type TerminalEvidenceProvider, type TerminalSessionSnapshot } from "@predicatesystems/authority";
+export interface TerminalRuntimeContext {
+    sessionId: string;
+    terminalId?: string;
+    cwd?: string;
+    command?: string;
+    /** Raw transcript text (will be canonicalized before hashing) */
+    transcript?: string;
+    observedAt?: string;
+    confidence?: number;
+    /** Environment variables (secrets will be redacted before hashing) */
+    env?: Record<string, string>;
+}
+export interface DesktopRuntimeContext {
+    appName?: string;
+    windowTitle?: string;
+    focusedRole?: string;
+    focusedName?: string;
+    /** Raw UI tree text (will be normalized before hashing) */
+    uiTreeText?: string;
+    /** Pre-computed UI tree hash (bypasses canonicalization) */
+    uiTreeHash?: string;
+    observedAt?: string;
+    confidence?: number;
+}
+export declare class OpenClawTerminalEvidenceProvider implements TerminalEvidenceProvider {
+    private readonly capture;
+    constructor(capture: () => Promise<TerminalRuntimeContext> | TerminalRuntimeContext);
+    captureTerminalSnapshot(): Promise<TerminalSessionSnapshot>;
+}
+export declare class OpenClawDesktopAccessibilityEvidenceProvider implements DesktopAccessibilityEvidenceProvider {
+    private readonly capture;
+    constructor(capture: () => Promise<DesktopRuntimeContext> | DesktopRuntimeContext);
+    captureAccessibilitySnapshot(): Promise<DesktopAccessibilitySnapshot>;
+}
+export interface BuildEvidenceOptions {
+    /**
+     * Use canonical hashing with proper normalization.
+     * When true, applies ANSI stripping, timestamp normalization, whitespace
+     * collapsing, and other canonicalization rules for reproducible hashes.
+     * @default true
+     */
+    useCanonicalHash?: boolean;
+}
+export declare function buildTerminalEvidenceFromProvider(provider: TerminalEvidenceProvider, options?: BuildEvidenceOptions): Promise<StateEvidence>;
+export declare function buildDesktopEvidenceFromProvider(provider: DesktopAccessibilityEvidenceProvider, options?: BuildEvidenceOptions): Promise<StateEvidence>;

package/dist/src/non-web-evidence.js

@@ -0,0 +1,54 @@
+import { buildDesktopAccessibilityStateEvidence, buildTerminalStateEvidence, } from "@predicatesystems/authority";
+export class OpenClawTerminalEvidenceProvider {
+    capture;
+    constructor(capture) {
+        this.capture = capture;
+    }
+    async captureTerminalSnapshot() {
+        const runtime = await this.capture();
+        return {
+            session_id: runtime.sessionId,
+            terminal_id: runtime.terminalId,
+            cwd: runtime.cwd,
+            command: runtime.command,
+            // Pass raw transcript - canonicalization happens in buildTerminalStateEvidence
+            // when useCanonicalHash is enabled. The field is named transcript_hash for
+            // backward compatibility but carries raw text when canonical hashing is used.
+            transcript_hash: runtime.transcript ?? "",
+            observed_at: runtime.observedAt ?? new Date().toISOString(),
+            confidence: runtime.confidence,
+        };
+    }
+}
+export class OpenClawDesktopAccessibilityEvidenceProvider {
+    capture;
+    constructor(capture) {
+        this.capture = capture;
+    }
+    async captureAccessibilitySnapshot() {
+        const runtime = await this.capture();
+        // Pass raw UI tree text - canonicalization happens in buildDesktopAccessibilityStateEvidence
+        // when useCanonicalHash is enabled. Use pre-computed hash if available for legacy mode.
+        // The field is named ui_tree_hash for backward compatibility but carries raw text
+        // when canonical hashing is used.
+        return {
+            app_name: runtime.appName,
+            window_title: runtime.windowTitle,
+            focused_role: runtime.focusedRole,
+            focused_name: runtime.focusedName,
+            ui_tree_hash: runtime.uiTreeHash ?? runtime.uiTreeText ?? "",
+            observed_at: runtime.observedAt ?? new Date().toISOString(),
+            confidence: runtime.confidence,
+        };
+    }
+}
+export async function buildTerminalEvidenceFromProvider(provider, options = {}) {
+    const snapshot = await provider.captureTerminalSnapshot();
+    const useCanonicalHash = options.useCanonicalHash ?? true;
+    return buildTerminalStateEvidence({ snapshot, useCanonicalHash });
+}
+export async function buildDesktopEvidenceFromProvider(provider, options = {}) {
+    const snapshot = await provider.captureAccessibilitySnapshot();
+    const useCanonicalHash = options.useCanonicalHash ?? true;
+    return buildDesktopAccessibilityStateEvidence({ snapshot, useCanonicalHash });
+}

package/dist/src/openclaw-hooks.d.ts

@@ -0,0 +1,27 @@
+import type { ToolAdapter } from "./adapter.js";
+export declare class HookEnvelope {
+    readonly toolName: string;
+    readonly args: Record<string, unknown>;
+    readonly sessionId: string;
+    readonly source: string;
+    readonly tenantId?: string;
+    readonly userId?: string;
+    readonly traceId?: string;
+    constructor(params: {
+        toolName: string;
+        args: Record<string, unknown>;
+        sessionId: string;
+        source: string;
+        tenantId?: string;
+        userId?: string;
+        traceId?: string;
+    });
+    context(): Record<string, unknown>;
+}
+export declare class OpenClawHooks {
+    private readonly adapter;
+    constructor(adapter: Pick<ToolAdapter, "runShell" | "readFile" | "httpRequest">);
+    onCmdRun(envelope: HookEnvelope, execute: (args: Record<string, unknown>) => Promise<unknown>): Promise<unknown>;
+    onFsRead(envelope: HookEnvelope, execute: (args: Record<string, unknown>) => Promise<unknown>): Promise<unknown>;
+    onHttpRequest(envelope: HookEnvelope, execute: (args: Record<string, unknown>) => Promise<unknown>): Promise<unknown>;
+}

package/dist/src/openclaw-hooks.js

@@ -0,0 +1,54 @@
+export class HookEnvelope {
+    toolName;
+    args;
+    sessionId;
+    source;
+    tenantId;
+    userId;
+    traceId;
+    constructor(params) {
+        this.toolName = params.toolName;
+        this.args = params.args;
+        this.sessionId = params.sessionId;
+        this.source = params.source;
+        this.tenantId = params.tenantId;
+        this.userId = params.userId;
+        this.traceId = params.traceId;
+    }
+    context() {
+        return {
+            session_id: this.sessionId,
+            source: this.source,
+            tenant_id: this.tenantId,
+            user_id: this.userId,
+            trace_id: this.traceId,
+        };
+    }
+}
+export class OpenClawHooks {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    onCmdRun(envelope, execute) {
+        return this.adapter.runShell({
+            args: envelope.args,
+            context: envelope.context(),
+            execute,
+        });
+    }
+    onFsRead(envelope, execute) {
+        return this.adapter.readFile({
+            args: envelope.args,
+            context: envelope.context(),
+            execute,
+        });
+    }
+    onHttpRequest(envelope, execute) {
+        return this.adapter.httpRequest({
+            args: envelope.args,
+            context: envelope.context(),
+            execute,
+        });
+    }
+}