openclaw-brokerkit 0.1.0

package/dist/src/runtime.js

@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto";
+import { BrokerClient, BrokerError } from "./client.js";
+import { StateStore } from "./store.js";
+export class BrokerRuntime {
+    config;
+    hooks;
+    sources = new Map();
+    requests = new Map();
+    health = new Map();
+    store;
+    timer;
+    delivering = false;
+    constructor(config, hooks) {
+        this.config = config;
+        this.hooks = hooks;
+        for (const source of config.brokers)
+            this.sources.set(source.id, {
+                config: source,
+                client: new BrokerClient(source.endpoint, () => hooks.resolveCredential(source), source.requestTimeoutMs),
+                discovered: false,
+            });
+    }
+    async start(stateDir) {
+        this.store = new StateStore(stateDir);
+        this.store.retainSources([...this.sources.keys()]);
+        this.store.pruneExpired();
+        await Promise.all([...this.sources.values()].map((source) => this.startSource(source)));
+        this.timer = setInterval(() => {
+            void this.reconcileAll();
+            void this.deliverPending();
+        }, this.config.pollIntervalMs);
+        this.timer.unref();
+    }
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        for (const source of this.sources.values())
+            source.abort?.abort();
+        this.store?.close();
+        this.store = undefined;
+    }
+    snapshot() {
+        return {
+            sources: [...this.health.values()].sort((a, b) => a.id.localeCompare(b.id)),
+            requests: [...this.requests.values()].sort((a, b) => b.requested_at.localeCompare(a.requested_at)),
+            synchronizedAt: new Date().toISOString(),
+            deliveryFailures: this.store?.failedDeliveryCount() ?? 0,
+        };
+    }
+    async decide(handle, action, expectedRevision, actor, options = {}) {
+        const resolved = this.requireStore().resolve(handle);
+        if (!resolved)
+            throw new Error("request_not_found");
+        const source = this.sources.get(resolved.sourceId);
+        if (!source)
+            throw new Error("source_unavailable");
+        const current = await source.client.get(resolved.requestId);
+        if (current.revision !== resolved.revision ||
+            current.revision !== expectedRevision)
+            throw new Error("revision_stale");
+        if (!current.allowed_actions.includes(action))
+            throw new Error("action_not_allowed");
+        if (options.constraints) {
+            const bounds = current.approval_bounds;
+            if (action !== "approve" ||
+                !bounds ||
+                (options.constraints.duration_seconds !== undefined &&
+                    options.constraints.duration_seconds > bounds.max_duration_seconds) ||
+                (options.constraints.max_uses !== undefined &&
+                    options.constraints.max_uses > bounds.max_uses))
+                throw new Error("action_not_allowed");
+        }
+        const decision = {
+            expected_revision: expectedRevision,
+            idempotency_key: deterministicDecisionKey(resolved.sourceId, resolved.requestId, expectedRevision, action, actor),
+            on_behalf_of: actor,
+            ...(options.reason ? { decision_reason: options.reason } : {}),
+            ...(options.constraints ? { constraints: options.constraints } : {}),
+        };
+        const updated = await this.decideWithRecovery(source, resolved.requestId, action, decision);
+        this.accept(source, updated);
+        return this.requests.get(handle) ?? this.project(source, updated, handle);
+    }
+    subscribe(value) {
+        const subscription = this.requireStore().subscribe(value);
+        for (const handle of this.requests.keys())
+            this.requireStore().enqueue(handle);
+        void this.deliverPending();
+        return subscription;
+    }
+    unsubscribe(value) {
+        return this.requireStore().unsubscribe(value);
+    }
+    subscriptions() {
+        return this.requireStore().subscriptions();
+    }
+    async startSource(source) {
+        try {
+            await this.ensureDiscovered(source);
+            await this.reconcile(source);
+        }
+        catch (error) {
+            this.markUnhealthy(source, error);
+        }
+        this.watch(source);
+    }
+    async decideWithRecovery(source, requestId, action, decision) {
+        try {
+            return await source.client.decide(requestId, action, decision);
+        }
+        catch (error) {
+            if (error instanceof BrokerError)
+                throw error;
+            try {
+                const observed = await source.client.get(requestId);
+                this.accept(source, observed);
+            }
+            catch {
+                throw new Error("source_unavailable");
+            }
+            try {
+                return await source.client.decide(requestId, action, decision);
+            }
+            catch (retryError) {
+                if (retryError instanceof BrokerError)
+                    throw retryError;
+                throw new Error("source_unavailable");
+            }
+        }
+    }
+    async reconcileAll() {
+        await Promise.all([...this.sources.values()].map((source) => this.ensureDiscovered(source)
+            .then(() => this.reconcile(source))
+            .catch((error) => this.markUnhealthy(source, error))));
+    }
+    async reconcile(source) {
+        const seen = new Set();
+        let eventCursor;
+        for (const status of ["pending", "active"]) {
+            let cursor;
+            do {
+                const page = await source.client.list(status, cursor);
+                eventCursor ??= page.event_cursor;
+                for (const request of page.requests) {
+                    seen.add(request.id);
+                    this.accept(source, request);
+                }
+                cursor = page.next_cursor;
+            } while (cursor);
+        }
+        for (const request of [...this.requests.values()])
+            if (request.sourceId === source.config.id && !seen.has(request.id)) {
+                this.requests.delete(request.handle);
+                this.requireStore().remove(source.config.id, request.id);
+            }
+        this.requireStore().retainRequests(source.config.id, seen);
+        this.requireStore().pruneExpired();
+        if (eventCursor)
+            this.requireStore().setCursor(source.config.id, eventCursor);
+        this.markHealthy(source);
+    }
+    watch(source) {
+        source.abort?.abort();
+        const abort = new AbortController();
+        source.abort = abort;
+        void (async () => {
+            let delay = 250;
+            while (!abort.signal.aborted) {
+                try {
+                    await this.ensureDiscovered(source);
+                    for await (const event of source.client.events(this.requireStore().cursor(source.config.id), abort.signal)) {
+                        const current = await source.client.get(event.request_id);
+                        this.accept(source, current);
+                        this.requireStore().setCursor(source.config.id, event.cursor);
+                        this.markHealthy(source);
+                        delay = 250;
+                    }
+                }
+                catch (error) {
+                    if (abort.signal.aborted)
+                        return;
+                    let recovered = false;
+                    if (error instanceof Error &&
+                        "code" in error &&
+                        error.code === "cursor_expired") {
+                        try {
+                            await this.reconcile(source);
+                            recovered = true;
+                        }
+                        catch (reconcileError) {
+                            this.markUnhealthy(source, reconcileError);
+                        }
+                    }
+                    if (!recovered)
+                        this.markUnhealthy(source, error);
+                    await sleep(delay);
+                    delay = Math.min(delay * 2, 30_000);
+                }
+            }
+        })();
+    }
+    async ensureDiscovered(source) {
+        if (source.discovered)
+            return;
+        await source.client.discover();
+        source.discovered = true;
+    }
+    markHealthy(source) {
+        this.health.set(source.config.id, {
+            id: source.config.id,
+            label: source.config.label,
+            healthy: true,
+            lastSyncAt: new Date().toISOString(),
+        });
+    }
+    accept(source, request) {
+        if (request.status !== "pending" && request.status !== "active") {
+            this.requireStore().remove(source.config.id, request.id);
+            for (const [handle, current] of this.requests)
+                if (current.sourceId === source.config.id && current.id === request.id)
+                    this.requests.delete(handle);
+            return;
+        }
+        const expires = Date.parse(request.pending_expires_at ??
+            request.active_expires_at ??
+            new Date(Date.now() + 86_400_000).toISOString());
+        const handle = this.requireStore().handle(source.config.id, request.id, request.revision, expires);
+        for (const [old, current] of this.requests)
+            if (current.sourceId === source.config.id &&
+                current.id === request.id &&
+                old !== handle)
+                this.requests.delete(old);
+        this.requests.set(handle, this.project(source, request, handle));
+        this.requireStore().enqueue(handle);
+        void this.deliverPending();
+    }
+    project(source, request, handle) {
+        return {
+            ...request,
+            sourceId: source.config.id,
+            sourceLabel: source.config.label,
+            handle,
+        };
+    }
+    markUnhealthy(source, error) {
+        const message = error instanceof Error ? error.message : "source unavailable";
+        this.health.set(source.config.id, {
+            id: source.config.id,
+            label: source.config.label,
+            healthy: false,
+            error: safeError(message),
+        });
+        this.hooks.log("warn", `BrokerKit source ${source.config.id} unavailable: ${safeError(message)}`);
+    }
+    requireStore() {
+        if (!this.store)
+            throw new Error("BrokerKit runtime is not started");
+        return this.store;
+    }
+    async deliverPending() {
+        if (this.delivering || !this.store)
+            return;
+        this.delivering = true;
+        try {
+            await Promise.all(this.store
+                .due(this.config.notificationConcurrency)
+                .map(async (delivery) => {
+                const request = this.requests.get(delivery.handle);
+                if (!request)
+                    return;
+                try {
+                    await this.hooks.deliver(delivery, notificationText(request));
+                    this.store?.markDelivered(delivery.id, delivery.handle);
+                }
+                catch {
+                    this.store?.markDeliveryError(delivery.id, delivery.handle, delivery.attempts);
+                }
+            }));
+        }
+        finally {
+            this.delivering = false;
+        }
+    }
+}
+function deterministicDecisionKey(source, request, revision, action, actor) {
+    return createHash("sha256")
+        .update([
+        "brokerkit-decision-v1",
+        source,
+        request,
+        String(revision),
+        action,
+        actor,
+    ].join("\0"))
+        .digest("base64url");
+}
+function safeError(value) {
+    return value.replace(/[\r\n]/g, " ").slice(0, 200);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function notificationText(request) {
+    return [
+        `${request.sourceLabel}: ${request.presentation.title}`,
+        request.presentation.summary ?? "",
+        `Handle: ${request.handle}`,
+        ...request.allowed_actions.map((action) => `/brokerkit ${action} ${request.handle}`),
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/src/store.js

@@ -0,0 +1,235 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const SCHEMA_VERSION = 2;
+export class StateStore {
+    db;
+    constructor(stateDir) {
+        const directory = path.join(stateDir, "plugins", "brokerkit");
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        assertPrivateDirectory(directory);
+        const databasePath = path.join(directory, "state.sqlite");
+        if (existsSync(databasePath))
+            assertPrivateDatabase(databasePath);
+        else
+            closeSync(openSync(databasePath, "wx", 0o600));
+        this.db = new DatabaseSync(databasePath);
+        this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000");
+        const version = this.db.prepare("PRAGMA user_version").get();
+        if (version.user_version !== 0 && version.user_version !== SCHEMA_VERSION)
+            throw new Error(`unsupported BrokerKit state version ${version.user_version}`);
+        if (version.user_version === 0)
+            this.createSchema();
+    }
+    close() {
+        this.db.close();
+    }
+    cursor(sourceId) {
+        return this.db
+            .prepare("SELECT cursor FROM source_cursor WHERE source_id=?")
+            .get(sourceId)?.cursor;
+    }
+    setCursor(sourceId, cursor) {
+        this.db
+            .prepare("INSERT INTO source_cursor VALUES(?,?) ON CONFLICT(source_id) DO UPDATE SET cursor=excluded.cursor")
+            .run(sourceId, cursor);
+    }
+    retainSources(sourceIds) {
+        const keep = new Set(sourceIds);
+        const rows = this.db
+            .prepare("SELECT source_id FROM source_cursor")
+            .all();
+        const remove = this.db.prepare("DELETE FROM source_cursor WHERE source_id=?");
+        this.transaction(() => {
+            for (const row of rows)
+                if (!keep.has(row.source_id))
+                    remove.run(row.source_id);
+        });
+    }
+    handle(sourceId, requestId, revision, expiresAtMs) {
+        const existing = this.db
+            .prepare("SELECT handle FROM request_handle WHERE source_id=? AND request_id=? AND revision=?")
+            .get(sourceId, requestId, revision);
+        if (existing)
+            return existing.handle;
+        const handle = randomBytes(16).toString("base64url");
+        this.transaction(() => {
+            this.db
+                .prepare("DELETE FROM request_handle WHERE source_id=? AND request_id=? AND revision<>?")
+                .run(sourceId, requestId, revision);
+            this.db
+                .prepare("INSERT INTO request_handle VALUES(?,?,?,?,?)")
+                .run(handle, sourceId, requestId, revision, expiresAtMs);
+        });
+        return handle;
+    }
+    resolve(handle) {
+        const value = this.db
+            .prepare("SELECT source_id,request_id,revision FROM request_handle WHERE handle=? AND expires_at_ms>?")
+            .get(handle, Date.now());
+        return (value && {
+            sourceId: value.source_id,
+            requestId: value.request_id,
+            revision: value.revision,
+        });
+    }
+    remove(sourceId, requestId) {
+        this.db
+            .prepare("DELETE FROM request_handle WHERE source_id=? AND request_id=?")
+            .run(sourceId, requestId);
+    }
+    retainRequests(sourceId, requestIds) {
+        const rows = this.db
+            .prepare("SELECT DISTINCT request_id FROM request_handle WHERE source_id=?")
+            .all(sourceId);
+        const remove = this.db.prepare("DELETE FROM request_handle WHERE source_id=? AND request_id=?");
+        this.transaction(() => {
+            for (const row of rows)
+                if (!requestIds.has(row.request_id))
+                    remove.run(sourceId, row.request_id);
+        });
+    }
+    pruneExpired(now = Date.now()) {
+        this.db
+            .prepare("DELETE FROM request_handle WHERE expires_at_ms<=?")
+            .run(now);
+    }
+    subscribe(value) {
+        const normalized = [
+            value.channel,
+            value.target,
+            value.accountId ?? "",
+            value.threadId ?? "",
+        ].join("\0");
+        const id = createHash("sha256")
+            .update("brokerkit-subscription\0")
+            .update(normalized)
+            .digest("hex");
+        this.db
+            .prepare("INSERT OR IGNORE INTO channel_subscription VALUES(?,?,?,?,?)")
+            .run(id, value.channel, value.target, value.accountId ?? null, value.threadId ?? null);
+        return { id, ...value };
+    }
+    unsubscribe(value) {
+        const result = this.db
+            .prepare("DELETE FROM channel_subscription WHERE channel=? AND target=? AND account_id IS ? AND thread_id IS ?")
+            .run(value.channel, value.target, value.accountId ?? null, value.threadId ?? null);
+        return result.changes > 0;
+    }
+    subscriptions() {
+        return this.db
+            .prepare("SELECT * FROM channel_subscription ORDER BY id")
+            .all().map((row) => ({
+            id: row.id,
+            channel: row.channel,
+            target: row.target,
+            ...(row.account_id ? { accountId: row.account_id } : {}),
+            ...(row.thread_id ? { threadId: row.thread_id } : {}),
+        }));
+    }
+    enqueue(handle) {
+        this.db
+            .prepare("INSERT OR IGNORE INTO notification_delivery SELECT id,?,'pending',0,? FROM channel_subscription")
+            .run(handle, Date.now());
+    }
+    due(limit) {
+        return this.db
+            .prepare("SELECT s.*,d.handle,d.attempts FROM notification_delivery d JOIN channel_subscription s ON s.id=d.subscription_id WHERE d.state IN ('pending','error') AND d.attempts<8 AND d.next_attempt_at_ms<=? ORDER BY d.next_attempt_at_ms LIMIT ?")
+            .all(Date.now(), limit).map((row) => ({
+            id: row.id,
+            channel: row.channel,
+            target: row.target,
+            handle: row.handle,
+            attempts: row.attempts,
+            ...(row.account_id ? { accountId: row.account_id } : {}),
+            ...(row.thread_id ? { threadId: row.thread_id } : {}),
+        }));
+    }
+    markDelivered(subscriptionId, handle) {
+        this.db
+            .prepare("UPDATE notification_delivery SET state='sent',attempts=attempts+1 WHERE subscription_id=? AND handle=?")
+            .run(subscriptionId, handle);
+    }
+    markDeliveryError(subscriptionId, handle, attempts) {
+        const boundedAttempts = Math.min(attempts + 1, 8);
+        const delay = Math.min(300_000, 1000 * 2 ** boundedAttempts);
+        this.db
+            .prepare("UPDATE notification_delivery SET state='error',attempts=?,next_attempt_at_ms=? WHERE subscription_id=? AND handle=?")
+            .run(boundedAttempts, Date.now() + delay, subscriptionId, handle);
+    }
+    failedDeliveryCount() {
+        const row = this.db
+            .prepare("SELECT count(*) AS count FROM notification_delivery WHERE state='error' AND attempts>=8")
+            .get();
+        return row.count;
+    }
+    transaction(operation) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = operation();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    createSchema() {
+        this.transaction(() => {
+            this.db.exec(`
+        CREATE TABLE source_cursor(
+          source_id TEXT PRIMARY KEY,
+          cursor TEXT NOT NULL CHECK(length(cursor) BETWEEN 1 AND 4096)
+        );
+        CREATE TABLE request_handle(
+          handle TEXT PRIMARY KEY CHECK(length(handle) >= 22),
+          source_id TEXT NOT NULL,
+          request_id TEXT NOT NULL,
+          revision INTEGER NOT NULL CHECK(revision > 0),
+          expires_at_ms INTEGER NOT NULL CHECK(expires_at_ms > 0),
+          UNIQUE(source_id, request_id, revision)
+        );
+        CREATE TABLE channel_subscription(
+          id TEXT PRIMARY KEY CHECK(length(id) = 64),
+          channel TEXT NOT NULL CHECK(length(channel) > 0),
+          target TEXT NOT NULL CHECK(length(target) > 0),
+          account_id TEXT,
+          thread_id TEXT,
+          UNIQUE(channel, target, account_id, thread_id)
+        );
+        CREATE TABLE notification_delivery(
+          subscription_id TEXT NOT NULL REFERENCES channel_subscription(id)
+            ON DELETE CASCADE,
+          handle TEXT NOT NULL REFERENCES request_handle(handle) ON DELETE CASCADE,
+          state TEXT NOT NULL CHECK(state IN ('pending', 'sent', 'error')),
+          attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts BETWEEN 0 AND 8),
+          next_attempt_at_ms INTEGER NOT NULL CHECK(next_attempt_at_ms >= 0),
+          PRIMARY KEY(subscription_id, handle)
+        );
+        PRAGMA user_version=${SCHEMA_VERSION};
+      `);
+        });
+    }
+}
+function assertPrivateDirectory(directory) {
+    const stat = lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error("BrokerKit state directory must be a real directory");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error("BrokerKit state directory has an unsafe owner");
+    if ((stat.mode & 0o077) !== 0)
+        throw new Error("BrokerKit state directory permissions must be 0700");
+}
+function assertPrivateDatabase(databasePath) {
+    const stat = lstatSync(databasePath);
+    if (stat.isSymbolicLink())
+        throw new Error("BrokerKit state database must not be a symlink");
+    if (!stat.isFile())
+        throw new Error("BrokerKit state database must be a regular file");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error("BrokerKit state database has an unsafe owner");
+    if ((stat.mode & 0o177) !== 0)
+        throw new Error("BrokerKit state database permissions must be 0600");
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};