@advicenxt/sbp-server 0.1.0

package/benchmarks/bench.ts

@@ -0,0 +1,272 @@
+/**
+ * SBP Benchmark Suite
+ *
+ * Measures performance characteristics of the core blackboard operations.
+ * Run: npx tsx benchmarks/bench.ts
+ */
+
+import { Blackboard } from "../src/blackboard.js";
+import { MemoryStore } from "../src/store.js";
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function formatOps(count: number, durationMs: number): string {
+    const opsPerSec = Math.round((count / durationMs) * 1000);
+    return `${opsPerSec.toLocaleString()} ops/sec`;
+}
+
+function formatDuration(ms: number): string {
+    if (ms < 1) return `${(ms * 1000).toFixed(0)}µs`;
+    if (ms < 1000) return `${ms.toFixed(2)}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+
+function runBench(name: string, fn: () => void, iterations: number = 100_000): void {
+    // Warmup
+    for (let i = 0; i < Math.min(1000, iterations / 10); i++) fn();
+
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) fn();
+    const elapsed = performance.now() - start;
+
+    const avg = elapsed / iterations;
+    console.log(
+        `  ${name.padEnd(45)} ${formatOps(iterations, elapsed).padStart(15)}  (avg ${formatDuration(avg)})`
+    );
+}
+
+// ============================================================================
+// BENCHMARKS
+// ============================================================================
+
+function benchEmitNew(): void {
+    const bb = new Blackboard();
+
+    console.log("\n📤 EMIT (new pheromone, no merge)");
+    let i = 0;
+    runBench("emit new pheromone", () => {
+        bb.emit({
+            trail: "bench.signals",
+            type: `type-${i++}`,
+            intensity: 0.8,
+            merge_strategy: "new",
+        });
+    }, 50_000);
+}
+
+function benchEmitReinforce(): void {
+    const bb = new Blackboard();
+    bb.emit({
+        trail: "bench.signals",
+        type: "target",
+        intensity: 0.5,
+        payload: { key: "value" },
+    });
+
+    console.log("\n🔁 EMIT (reinforce existing)");
+    runBench("emit reinforce", () => {
+        bb.emit({
+            trail: "bench.signals",
+            type: "target",
+            intensity: 0.7,
+            payload: { key: "value" },
+            merge_strategy: "reinforce",
+        });
+    }, 50_000);
+}
+
+function benchSniff(pheromoneCount: number): void {
+    const bb = new Blackboard();
+    for (let i = 0; i < pheromoneCount; i++) {
+        bb.emit({
+            trail: `bench.trail-${i % 10}`,
+            type: `type-${i}`,
+            intensity: Math.random(),
+            merge_strategy: "new",
+        });
+    }
+
+    console.log(`\n👃 SNIFF (${pheromoneCount.toLocaleString()} pheromones in store)`);
+
+    runBench("sniff all (no filters)", () => {
+        bb.sniff({ limit: 100 });
+    }, 10_000);
+
+    runBench("sniff single trail", () => {
+        bb.sniff({ trails: ["bench.trail-0"], limit: 100 });
+    }, 10_000);
+
+    runBench("sniff with min_intensity 0.5", () => {
+        bb.sniff({ min_intensity: 0.5, limit: 100 });
+    }, 10_000);
+
+    runBench("sniff with tags filter", () => {
+        bb.sniff({ tags: { any: ["tag-a"] }, limit: 100 });
+    }, 10_000);
+}
+
+function benchConditionEvaluation(): void {
+    const bb = new Blackboard();
+    for (let i = 0; i < 1000; i++) {
+        bb.emit({
+            trail: "bench.eval",
+            type: `signal-${i % 5}`,
+            intensity: 0.3 + Math.random() * 0.7,
+            merge_strategy: "new",
+        });
+    }
+
+    // Register a composite scent
+    bb.registerScent({
+        scent_id: "bench-scent",
+        agent_endpoint: "http://localhost:9999",
+        condition: {
+            type: "composite",
+            operator: "and",
+            conditions: [
+                {
+                    type: "threshold",
+                    trail: "bench.eval",
+                    signal_type: "signal-0",
+                    aggregation: "max",
+                    operator: ">=",
+                    value: 0.7,
+                },
+                {
+                    type: "threshold",
+                    trail: "bench.eval",
+                    signal_type: "signal-1",
+                    aggregation: "count",
+                    operator: ">=",
+                    value: 3,
+                },
+            ],
+        },
+        cooldown_ms: 0,
+    });
+
+    console.log("\n🧠 CONDITION EVALUATION (1,000 pheromones, composite AND)");
+    runBench("evaluateScents (sync part)", () => {
+        // Evaluate without triggering (cooldown = 0 means it fires and resets)
+        const pheromones = [...(bb as any).store.values()];
+        const { evaluateCondition } = require("../src/conditions.js");
+        evaluateCondition(
+            {
+                type: "composite",
+                operator: "and",
+                conditions: [
+                    {
+                        type: "threshold",
+                        trail: "bench.eval",
+                        signal_type: "signal-0",
+                        aggregation: "max",
+                        operator: ">=",
+                        value: 0.7,
+                    },
+                    {
+                        type: "threshold",
+                        trail: "bench.eval",
+                        signal_type: "signal-1",
+                        aggregation: "count",
+                        operator: ">=",
+                        value: 3,
+                    },
+                ],
+            },
+            { pheromones, now: Date.now(), emissionHistory: [] }
+        );
+    }, 10_000);
+}
+
+function benchGarbageCollection(): void {
+    const bb = new Blackboard({ defaultDecay: { type: "linear", rate_per_ms: 100 } });
+    for (let i = 0; i < 10_000; i++) {
+        bb.emit({
+            trail: "bench.gc",
+            type: `type-${i}`,
+            intensity: 0.5,
+            merge_strategy: "new",
+        });
+    }
+    // Let them evaporate
+    const delay = (ms: number) => {
+        const end = Date.now() + ms;
+        while (Date.now() < end) { }
+    };
+    delay(50);
+
+    console.log("\n🧹 GARBAGE COLLECTION (10,000 evaporated pheromones)");
+    const start = performance.now();
+    const removed = bb.gc();
+    const elapsed = performance.now() - start;
+    console.log(`  gc() removed ${removed.toLocaleString()} pheromones in ${formatDuration(elapsed)}`);
+}
+
+function benchStoreOperations(): void {
+    console.log("\n💾 STORE OPERATIONS (MemoryStore)");
+    const store = new MemoryStore();
+
+    runBench("store.set + store.get", () => {
+        const p = {
+            id: "test-id",
+            trail: "bench",
+            type: "test",
+            emitted_at: Date.now(),
+            last_reinforced_at: Date.now(),
+            initial_intensity: 0.5,
+            decay_model: { type: "exponential" as const, half_life_ms: 300000 },
+            payload: {},
+            tags: [],
+            ttl_floor: 0.01,
+        };
+        store.set("test-id", p);
+        store.get("test-id");
+    }, 100_000);
+
+    // Fill store then iterate
+    for (let i = 0; i < 10_000; i++) {
+        store.set(`p-${i}`, {
+            id: `p-${i}`,
+            trail: "bench",
+            type: "test",
+            emitted_at: Date.now(),
+            last_reinforced_at: Date.now(),
+            initial_intensity: 0.5,
+            decay_model: { type: "exponential" as const, half_life_ms: 300000 },
+            payload: {},
+            tags: [],
+            ttl_floor: 0.01,
+        });
+    }
+
+    runBench("store.values() iteration (10k entries)", () => {
+        let count = 0;
+        for (const _p of store.values()) count++;
+    }, 1_000);
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+console.log("═══════════════════════════════════════════════════════════════");
+console.log("  SBP Benchmark Suite");
+console.log("═══════════════════════════════════════════════════════════════");
+console.log(`  Node ${process.version} | ${process.platform} ${process.arch}`);
+console.log(`  Date: ${new Date().toISOString()}`);
+console.log("═══════════════════════════════════════════════════════════════");
+
+benchEmitNew();
+benchEmitReinforce();
+benchSniff(100);
+benchSniff(1_000);
+benchSniff(10_000);
+benchConditionEvaluation();
+benchGarbageCollection();
+benchStoreOperations();
+
+console.log("\n═══════════════════════════════════════════════════════════════");
+console.log("  Done.");
+console.log("═══════════════════════════════════════════════════════════════\n");

package/dist/auth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SBP Authentication Middleware
+ * Basic API key authentication for the SBP server
+ */
+import type { FastifyRequest, FastifyReply, HookHandlerDoneFunction } from "fastify";
+export interface AuthOptions {
+    /** List of valid API keys */
+    apiKeys?: string[];
+    /** Whether authentication is required (default: false) */
+    requireAuth?: boolean;
+}
+/**
+ * Create a Fastify onRequest hook for API key authentication.
+ *
+ * Checks the `Authorization: Bearer <key>` header against the
+ * configured list of API keys. Returns 401 with SBP error code
+ * -32005 (UNAUTHORIZED) if the key is missing or invalid.
+ */
+export declare function createAuthHook(options: AuthOptions): (request: FastifyRequest, reply: FastifyReply, done: HookHandlerDoneFunction) => void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAErF,MAAM,WAAW,WAAW;IACxB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAKD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,IAI3C,SAAS,cAAc,EACvB,OAAO,YAAY,EACnB,MAAM,uBAAuB,KAC9B,IAAI,CAyDV"}

package/dist/auth.js

@@ -0,0 +1,69 @@
+/**
+ * SBP Authentication Middleware
+ * Basic API key authentication for the SBP server
+ */
+/** Paths that skip authentication */
+const PUBLIC_PATHS = ["/health"];
+/**
+ * Create a Fastify onRequest hook for API key authentication.
+ *
+ * Checks the `Authorization: Bearer <key>` header against the
+ * configured list of API keys. Returns 401 with SBP error code
+ * -32005 (UNAUTHORIZED) if the key is missing or invalid.
+ */
+export function createAuthHook(options) {
+    const { apiKeys = [], requireAuth = false } = options;
+    return function authHook(request, reply, done) {
+        // Skip auth if not required
+        if (!requireAuth || apiKeys.length === 0) {
+            done();
+            return;
+        }
+        // Skip auth for public paths and OPTIONS
+        const url = request.url.split("?")[0];
+        if (PUBLIC_PATHS.includes(url) || request.method === "OPTIONS") {
+            done();
+            return;
+        }
+        // Extract bearer token
+        const authHeader = request.headers.authorization;
+        if (!authHeader) {
+            reply.status(401).send({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32005,
+                    message: "Unauthorized: Missing Authorization header",
+                },
+            });
+            return;
+        }
+        const parts = authHeader.split(" ");
+        if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer") {
+            reply.status(401).send({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32005,
+                    message: "Unauthorized: Invalid Authorization header format. Expected: Bearer <api-key>",
+                },
+            });
+            return;
+        }
+        const token = parts[1];
+        if (!apiKeys.includes(token)) {
+            reply.status(401).send({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32005,
+                    message: "Unauthorized: Invalid API key",
+                },
+            });
+            return;
+        }
+        // Valid key — attach agent info from token position (optional extension point)
+        done();
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,qCAAqC;AACrC,MAAM,YAAY,GAAG,CAAC,SAAS,CAAC,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IAC/C,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,WAAW,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAEtD,OAAO,SAAS,QAAQ,CACpB,OAAuB,EACvB,KAAmB,EACnB,IAA6B;QAE7B,4BAA4B;QAC5B,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvC,IAAI,EAAE,CAAC;YACP,OAAO;QACX,CAAC;QAED,yCAAyC;QACzC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7D,IAAI,EAAE,CAAC;YACP,OAAO;QACX,CAAC;QAED,uBAAuB;QACvB,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;QACjD,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE;oBACH,IAAI,EAAE,CAAC,KAAK;oBACZ,OAAO,EAAE,4CAA4C;iBACxD;aACJ,CAAC,CAAC;YACH,OAAO;QACX,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC5D,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE;oBACH,IAAI,EAAE,CAAC,KAAK;oBACZ,OAAO,EAAE,+EAA+E;iBAC3F;aACJ,CAAC,CAAC;YACH,OAAO;QACX,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE;oBACH,IAAI,EAAE,CAAC,KAAK;oBACZ,OAAO,EAAE,+BAA+B;iBAC3C;aACJ,CAAC,CAAC;YACH,OAAO;QACX,CAAC;QAED,+EAA+E;QAC/E,IAAI,EAAE,CAAC;IACX,CAAC,CAAC;AACN,CAAC"}

package/dist/blackboard.d.ts

@@ -0,0 +1,84 @@
+/**
+ * SBP Blackboard - Core State Management
+ */
+import type { PheromoneStore } from "./store.js";
+import type { DecayModel, EmitParams, EmitResult, SniffParams, SniffResult, RegisterScentParams, RegisterScentResult, DeregisterScentParams, DeregisterScentResult, EvaporateParams, EvaporateResult, InspectParams, InspectResult, TriggerPayload } from "./types.js";
+export interface BlackboardOptions {
+    /** Interval for scent evaluation in ms (default: 100) */
+    evaluationInterval?: number;
+    /** Default decay model for new pheromones */
+    defaultDecay?: DecayModel;
+    /** Default TTL floor for evaporation */
+    defaultTtlFloor?: number;
+    /** Maximum pheromones before GC triggers */
+    maxPheromones?: number;
+    /** Enable emission history tracking for rate conditions */
+    trackEmissionHistory?: boolean;
+    /** How long to keep emission history (ms) */
+    emissionHistoryWindow?: number;
+    /** Pluggable pheromone storage backend (default: MemoryStore) */
+    store?: PheromoneStore;
+}
+export interface TriggerHandler {
+    (payload: TriggerPayload): Promise<void>;
+}
+export declare class Blackboard {
+    private store;
+    private scents;
+    private triggerHandlers;
+    private emissionHistory;
+    private evaluationTimer;
+    private startTime;
+    private options;
+    constructor(options?: BlackboardOptions);
+    emit(params: EmitParams): EmitResult;
+    sniff(params?: SniffParams): SniffResult;
+    registerScent(params: RegisterScentParams): RegisterScentResult;
+    deregisterScent(params: DeregisterScentParams): DeregisterScentResult;
+    evaporate(params?: EvaporateParams): EvaporateResult;
+    inspect(params?: InspectParams): InspectResult;
+    /**
+     * Register a local handler for a scent
+     */
+    onTrigger(scentId: string, handler: TriggerHandler): void;
+    /**
+     * Remove a local trigger handler
+     */
+    offTrigger(scentId: string): void;
+    /**
+     * Start the background scent evaluation loop
+     */
+    start(): void;
+    /**
+     * Stop the background evaluation loop
+     */
+    stop(): void;
+    /**
+     * Evaluate all scents and trigger as needed
+     */
+    evaluateScents(): Promise<void>;
+    /**
+     * Determine if a scent should trigger based on mode
+     */
+    private shouldTrigger;
+    /**
+     * Dispatch a trigger to the agent
+     */
+    private dispatchTrigger;
+    /**
+     * Garbage collect evaporated pheromones
+     */
+    gc(): number;
+    /**
+     * Get raw pheromone count (for testing)
+     */
+    get size(): number;
+    /**
+     * Get scent count
+     */
+    get scentCount(): number;
+    private hashPayload;
+    private matchTags;
+    private pruneEmissionHistory;
+}
+//# sourceMappingURL=blackboard.d.ts.map

package/dist/blackboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blackboard.d.ts","sourceRoot":"","sources":["../src/blackboard.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAIV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,WAAW,EAEX,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,cAAc,EAEf,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,eAAe,CAAiE;IACxF,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,SAAS,CAAc;IAE/B,OAAO,CAAC,OAAO,CAA6C;gBAEhD,OAAO,GAAE,iBAAsB;IAgB3C,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU;IAoHpC,KAAK,CAAC,MAAM,GAAE,WAAgB,GAAG,WAAW;IAwE5C,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB;IAoD/D,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB;IAgBrE,SAAS,CAAC,MAAM,GAAE,eAAoB,GAAG,eAAe;IAgCxD,OAAO,CAAC,MAAM,GAAE,aAAkB,GAAG,aAAa;IA0DlD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAIzD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BrC;;OAEG;IACH,OAAO,CAAC,aAAa;IAgBrB;;OAEG;YACW,eAAe;IA6E7B;;OAEG;IACH,EAAE,IAAI,MAAM;IAiBZ;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,oBAAoB;CAI7B"}