@kognitivedev/shared 0.2.2

package/dist/streaming.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Multi-mode streaming protocol for agents and workflows.
+ *
+ * Inspired by LangGraph's 5 streaming modes:
+ * - values:   Full state snapshot after every step
+ * - updates:  State deltas only (what changed)
+ * - messages: Token-by-token LLM output
+ * - custom:   Application-specific events from user code (via emit())
+ * - debug:    Full execution trace with node entry/exit, tool I/O
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStreamModes = parseStreamModes;
+exports.createSSEEncoder = createSSEEncoder;
+exports.sseHeaders = sseHeaders;
+const VALID_MODES = new Set(["values", "updates", "messages", "custom", "debug"]);
+/**
+ * Parse and validate stream modes from a comma-separated string or array.
+ * Returns ["messages"] if input is empty/undefined (default mode).
+ */
+function parseStreamModes(input) {
+    if (!input)
+        return ["messages"];
+    const raw = Array.isArray(input) ? input : input.split(",").map(s => s.trim());
+    const modes = [];
+    for (const mode of raw) {
+        if (!VALID_MODES.has(mode)) {
+            throw new Error(`Invalid stream mode: "${mode}". Valid modes: ${[...VALID_MODES].join(", ")}`);
+        }
+        if (!modes.includes(mode)) {
+            modes.push(mode);
+        }
+    }
+    return modes.length > 0 ? modes : ["messages"];
+}
+const encoder = new TextEncoder();
+/**
+ * TransformStream that encodes StreamEvents into SSE wire format.
+ *
+ * Output format per event:
+ *   event: <event>\n
+ *   data: <JSON>\n
+ *   \n
+ */
+function createSSEEncoder() {
+    return new TransformStream({
+        transform(event, controller) {
+            const lines = [
+                `event: ${event.event}`,
+                `data: ${JSON.stringify(event.data)}`,
+                "",
+                "",
+            ].join("\n");
+            controller.enqueue(encoder.encode(lines));
+        },
+    });
+}
+/**
+ * Create SSE Response headers.
+ */
+function sseHeaders() {
+    return {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+    };
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Lightweight OpenTelemetry wrapper.
+ *
+ * Uses @opentelemetry/api as an optional peer dependency.
+ * If not installed, all functions are no-ops — zero overhead.
+ * Users bring their own OTEL SDK and exporters.
+ *
+ * @example
+ * ```ts
+ * import { withSpan } from '@kognitivedev/shared';
+ *
+ * const result = await withSpan('agent.generate', async (span) => {
+ *   span.setAttribute('agent.name', 'support');
+ *   return await generateText({ ... });
+ * });
+ * ```
+ */
+interface SpanLike {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    end(): void;
+    isRecording(): boolean;
+}
+/**
+ * Create a span. Returns a no-op span if OTEL is not configured.
+ */
+export declare function createSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanLike;
+/**
+ * End a span, optionally recording an error.
+ */
+export declare function endSpan(span: SpanLike, error?: Error): void;
+/**
+ * Execute a function within a traced span.
+ * If OTEL is not configured, runs the function directly with no overhead.
+ */
+export declare function withSpan<T>(name: string, fn: (span: SpanLike) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+export type { SpanLike };

package/dist/telemetry.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Lightweight OpenTelemetry wrapper.
+ *
+ * Uses @opentelemetry/api as an optional peer dependency.
+ * If not installed, all functions are no-ops — zero overhead.
+ * Users bring their own OTEL SDK and exporters.
+ *
+ * @example
+ * ```ts
+ * import { withSpan } from '@kognitivedev/shared';
+ *
+ * const result = await withSpan('agent.generate', async (span) => {
+ *   span.setAttribute('agent.name', 'support');
+ *   return await generateText({ ... });
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpan = createSpan;
+exports.endSpan = endSpan;
+exports.withSpan = withSpan;
+// Lazy-loaded OTEL references
+let _tracer = null;
+let _otelLoaded = false;
+function getTracer() {
+    if (_otelLoaded)
+        return _tracer;
+    _otelLoaded = true;
+    try {
+        // Dynamic require — only succeeds if @opentelemetry/api is installed
+        const api = require("@opentelemetry/api");
+        const tracer = api.trace.getTracer("@kognitivedev/shared");
+        // Check if it's a NoopTracer (no SDK configured)
+        const testSpan = tracer.startSpan("__test__");
+        const isNoop = !testSpan.isRecording();
+        testSpan.end();
+        if (isNoop) {
+            _tracer = null;
+        }
+        else {
+            _tracer = tracer;
+        }
+    }
+    catch (_a) {
+        // @opentelemetry/api not installed — all no-ops
+        _tracer = null;
+    }
+    return _tracer;
+}
+// No-op span for when OTEL is not available
+const noopSpan = {
+    setAttribute: () => { },
+    setStatus: () => { },
+    end: () => { },
+    isRecording: () => false,
+};
+/**
+ * Create a span. Returns a no-op span if OTEL is not configured.
+ */
+function createSpan(name, attributes) {
+    const tracer = getTracer();
+    if (!tracer)
+        return noopSpan;
+    const span = tracer.startSpan(name);
+    if (attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+            span.setAttribute(key, value);
+        }
+    }
+    return span;
+}
+/**
+ * End a span, optionally recording an error.
+ */
+function endSpan(span, error) {
+    if (error) {
+        span.setStatus({ code: 2, message: error.message }); // SpanStatusCode.ERROR = 2
+    }
+    span.end();
+}
+/**
+ * Execute a function within a traced span.
+ * If OTEL is not configured, runs the function directly with no overhead.
+ */
+async function withSpan(name, fn, attributes) {
+    const span = createSpan(name, attributes);
+    try {
+        const result = await fn(span);
+        span.end();
+        return result;
+    }
+    catch (error) {
+        endSpan(span, error);
+        throw error;
+    }
+}

package/dist/template.d.ts

@@ -0,0 +1,2 @@
+export type TemplateVariables = Record<string, string | boolean>;
+export declare function renderTemplate(template: string, variables: TemplateVariables): string;

package/dist/template.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = renderTemplate;
+// Use the pre-built dist to avoid `require.extensions` warning in webpack/Next.js
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const handlebars_1 = __importDefault(require("handlebars/dist/cjs/handlebars"));
+function renderTemplate(template, variables) {
+    const compiled = handlebars_1.default.compile(template, { noEscape: true });
+    return compiled(variables);
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Unified resource identifier for multi-tenant operations.
+ * Used across all packages to identify the scope of operations.
+ */
+export interface ResourceId {
+    organizationId?: string;
+    projectId: string;
+    userId?: string;
+    sessionId?: string;
+}
+/**
+ * Generic result type for operations that can succeed or fail.
+ */
+export type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Helper to create a successful result.
+ */
+export declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Helper to create a failed result.
+ */
+export declare function err<E = Error>(error: E): Result<never, E>;
+/**
+ * Generic metadata record.
+ */
+export type Metadata = Record<string, unknown>;
+/**
+ * Disposable resource interface for cleanup.
+ */
+export interface Disposable {
+    dispose(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.err = err;
+/**
+ * Helper to create a successful result.
+ */
+function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Helper to create a failed result.
+ */
+function err(error) {
+    return { ok: false, error };
+}

package/dist/utils/id.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generate a unique ID using crypto.randomUUID.
+ */
+export declare function generateId(): string;

package/dist/utils/id.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateId = generateId;
+const crypto_1 = require("crypto");
+/**
+ * Generate a unique ID using crypto.randomUUID.
+ */
+function generateId() {
+    return (0, crypto_1.randomUUID)();
+}

package/dist/utils/retry.d.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "../logger";
+export interface RetryAttempt {
+    attempt: number;
+    error: {
+        message: string;
+        type: string;
+    };
+    delayMs: number;
+    timestamp: string;
+}
+export interface RetryMetadata {
+    totalAttempts: number;
+    attempts: RetryAttempt[];
+}
+export interface RetryOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    operationName?: string;
+    logger?: Logger;
+    /** When provided, retry attempt details are pushed into this object. */
+    collectRetryMetadata?: RetryMetadata;
+}
+/**
+ * Execute a function with exponential backoff retry.
+ * Extracted from EnhancedMemoryOrchestrator for shared use.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/retry.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+/**
+ * Execute a function with exponential backoff retry.
+ * Extracted from EnhancedMemoryOrchestrator for shared use.
+ */
+async function withRetry(fn, options = {}) {
+    var _a, _b;
+    const { maxRetries = 3, baseDelayMs = 100, operationName = "operation", logger, collectRetryMetadata, } = options;
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            const delay = Math.pow(2, attempt) * baseDelayMs;
+            if (collectRetryMetadata) {
+                collectRetryMetadata.totalAttempts = attempt;
+                collectRetryMetadata.attempts.push({
+                    attempt,
+                    error: { message: lastError.message, type: (_b = (_a = lastError.constructor) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : "Error" },
+                    delayMs: delay,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            if (attempt < maxRetries) {
+                logger === null || logger === void 0 ? void 0 : logger.warn(`Retry ${attempt}/${maxRetries} for ${operationName}`, { delay });
+                await new Promise((res) => setTimeout(res, delay));
+            }
+        }
+    }
+    logger === null || logger === void 0 ? void 0 : logger.error(`Operation ${operationName} failed after ${maxRetries} retries`, lastError);
+    throw lastError;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kognitivedev/shared",
+  "version": "0.2.2",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "Foundation utilities for the Kognitive AI framework",
+  "keywords": [
+    "kognitive",
+    "ai",
+    "utilities",
+    "events",
+    "cache",
+    "logger"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kognitivedev/kognitive",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://kognitive.dev"
+}

package/src/__tests__/shared.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+    InMemoryEventBus,
+    InMemoryCacheAdapter,
+    ConsoleLogger,
+    NoopLogger,
+    withRetry,
+    generateId,
+    ok,
+    err,
+    KognitiveError,
+    ValidationError,
+    NotFoundError,
+    TimeoutError,
+    ApprovalDeniedError,
+    RetryableError,
+} from "../index";
+
+// ─── EventBus ───
+
+describe("InMemoryEventBus", () => {
+    let bus: InMemoryEventBus;
+
+    beforeEach(() => {
+        bus = new InMemoryEventBus();
+    });
+
+    it("emits events to registered handlers", () => {
+        const handler = vi.fn();
+        bus.on("test", handler);
+        bus.emit("test", { value: 42 });
+        expect(handler).toHaveBeenCalledWith({ value: 42 });
+    });
+
+    it("supports multiple handlers for same event", () => {
+        const h1 = vi.fn();
+        const h2 = vi.fn();
+        bus.on("evt", h1);
+        bus.on("evt", h2);
+        bus.emit("evt", "data");
+        expect(h1).toHaveBeenCalledWith("data");
+        expect(h2).toHaveBeenCalledWith("data");
+    });
+
+    it("unsubscribes via returned function", () => {
+        const handler = vi.fn();
+        const unsub = bus.on("evt", handler);
+        unsub();
+        bus.emit("evt", "data");
+        expect(handler).not.toHaveBeenCalled();
+    });
+
+    it("once fires handler only once", () => {
+        const handler = vi.fn();
+        bus.once("evt", handler);
+        bus.emit("evt", 1);
+        bus.emit("evt", 2);
+        expect(handler).toHaveBeenCalledTimes(1);
+        expect(handler).toHaveBeenCalledWith(1);
+    });
+
+    it("removeAll clears specific event", () => {
+        const h1 = vi.fn();
+        const h2 = vi.fn();
+        bus.on("a", h1);
+        bus.on("b", h2);
+        bus.removeAll("a");
+        bus.emit("a", 1);
+        bus.emit("b", 2);
+        expect(h1).not.toHaveBeenCalled();
+        expect(h2).toHaveBeenCalled();
+    });
+
+    it("removeAll with no arg clears all events", () => {
+        const h1 = vi.fn();
+        const h2 = vi.fn();
+        bus.on("a", h1);
+        bus.on("b", h2);
+        bus.removeAll();
+        bus.emit("a", 1);
+        bus.emit("b", 2);
+        expect(h1).not.toHaveBeenCalled();
+        expect(h2).not.toHaveBeenCalled();
+    });
+
+    it("does not throw on emit with no handlers", () => {
+        expect(() => bus.emit("nonexistent", {})).not.toThrow();
+    });
+});
+
+// ─── Cache ───
+
+describe("InMemoryCacheAdapter", () => {
+    let cache: InMemoryCacheAdapter;
+
+    beforeEach(() => {
+        cache = new InMemoryCacheAdapter();
+    });
+
+    it("get returns null for missing key", async () => {
+        expect(await cache.get("missing")).toBeNull();
+    });
+
+    it("set and get round-trips", async () => {
+        await cache.set("key", { value: 42 });
+        expect(await cache.get("key")).toEqual({ value: 42 });
+    });
+
+    it("delete removes entry", async () => {
+        await cache.set("key", "value");
+        await cache.delete("key");
+        expect(await cache.get("key")).toBeNull();
+    });
+
+    it("TTL expires entries", async () => {
+        vi.useFakeTimers();
+        await cache.set("key", "value", 1); // 1 second TTL
+        expect(await cache.get("key")).toBe("value");
+        vi.advanceTimersByTime(2000);
+        expect(await cache.get("key")).toBeNull();
+        vi.useRealTimers();
+    });
+
+    it("reports size", async () => {
+        await cache.set("a", 1);
+        await cache.set("b", 2);
+        expect(cache.size).toBe(2);
+    });
+
+    it("clear removes all entries", async () => {
+        await cache.set("a", 1);
+        await cache.set("b", 2);
+        cache.clear();
+        expect(cache.size).toBe(0);
+    });
+});
+
+// ─── withRetry ───
+
+describe("withRetry", () => {
+    it("succeeds on first try", async () => {
+        const fn = vi.fn().mockResolvedValue("ok");
+        const result = await withRetry(fn, { maxRetries: 3 });
+        expect(result).toBe("ok");
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("retries and succeeds on second attempt", async () => {
+        const fn = vi.fn()
+            .mockRejectedValueOnce(new Error("fail"))
+            .mockResolvedValue("ok");
+        const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 1 });
+        expect(result).toBe("ok");
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it("throws after max retries", async () => {
+        const fn = vi.fn().mockRejectedValue(new Error("always fails"));
+        await expect(withRetry(fn, { maxRetries: 2, baseDelayMs: 1 })).rejects.toThrow("always fails");
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+});
+
+// ─── Utilities ───
+
+describe("generateId", () => {
+    it("returns a UUID string", () => {
+        const id = generateId();
+        expect(id).toMatch(/^[0-9a-f-]{36}$/);
+    });
+
+    it("generates unique IDs", () => {
+        const ids = new Set(Array.from({ length: 100 }, () => generateId()));
+        expect(ids.size).toBe(100);
+    });
+});
+
+describe("Result helpers", () => {
+    it("ok creates success result", () => {
+        const result = ok(42);
+        expect(result.ok).toBe(true);
+        if (result.ok) expect(result.value).toBe(42);
+    });
+
+    it("err creates failure result", () => {
+        const result = err(new Error("fail"));
+        expect(result.ok).toBe(false);
+        if (!result.ok) expect(result.error.message).toBe("fail");
+    });
+});
+
+// ─── Error Types ───
+
+describe("Error types", () => {
+    it("KognitiveError has code and name", () => {
+        const e = new KognitiveError("msg", "CODE");
+        expect(e.name).toBe("KognitiveError");
+        expect(e.code).toBe("CODE");
+        expect(e.message).toBe("msg");
+    });
+
+    it("ValidationError has field", () => {
+        const e = new ValidationError("bad input", "email");
+        expect(e.name).toBe("ValidationError");
+        expect(e.field).toBe("email");
+        expect(e.code).toBe("VALIDATION");
+    });
+
+    it("NotFoundError formats message", () => {
+        const e = new NotFoundError("User", "123");
+        expect(e.message).toBe("User not found: 123");
+        expect(e.code).toBe("NOT_FOUND");
+    });
+
+    it("TimeoutError has timeoutMs", () => {
+        const e = new TimeoutError("timed out", 5000);
+        expect(e.timeoutMs).toBe(5000);
+        expect(e.code).toBe("TIMEOUT");
+    });
+
+    it("ApprovalDeniedError has tool info", () => {
+        const e = new ApprovalDeniedError("search");
+        expect(e.message).toContain("search");
+        expect(e.code).toBe("APPROVAL_DENIED");
+    });
+
+    it("RetryableError is retryable", () => {
+        const e = new RetryableError("transient");
+        expect(e.code).toBe("RETRYABLE");
+    });
+});
+
+// ─── Logger ───
+
+describe("Loggers", () => {
+    it("ConsoleLogger logs without throwing", () => {
+        const logger = new ConsoleLogger("[Test]");
+        expect(() => logger.debug("test")).not.toThrow();
+        expect(() => logger.info("test")).not.toThrow();
+        expect(() => logger.warn("test")).not.toThrow();
+        expect(() => logger.error("test", new Error("e"))).not.toThrow();
+    });
+
+    it("NoopLogger does nothing", () => {
+        const logger = new NoopLogger();
+        expect(() => logger.debug("test")).not.toThrow();
+        expect(() => logger.info("test")).not.toThrow();
+    });
+});