@kognitivedev/shared 0.2.2

package/README.md

@@ -0,0 +1,43 @@
+# @kognitivedev/shared
+
+> Foundation utilities for the Kognitive AI framework — EventBus, Cache, Logger, Errors, Retry, and OpenTelemetry integration.
+
+## Installation
+
+```bash
+bun add @kognitivedev/shared
+```
+
+## Exports
+
+### Events
+- `InMemoryEventBus` — typed pub/sub: `emit()`, `on()`, `once()`, `removeAll()`
+
+### Cache
+- `InMemoryCacheAdapter` — TTL-based cache: `get()`, `set()`, `delete()`, `clear()`
+
+### Logger
+- `ConsoleLogger` — structured logging with prefix
+- `NoopLogger` — silent logger for testing
+
+### Errors
+- `KognitiveError`, `RetryableError`, `ValidationError`, `TimeoutError`, `NotFoundError`, `ApprovalDeniedError`
+
+### Utilities
+- `withRetry(fn, options)` — exponential backoff retry
+- `generateId()` — UUID generation
+
+### Telemetry
+- `withSpan(name, fn, attributes?)` — OpenTelemetry span wrapper (no-op if OTEL not installed)
+- `createSpan()`, `endSpan()` — manual span control
+
+### Streaming
+- `StreamMode` — `"values" | "updates" | "messages" | "custom" | "debug"`
+- `StreamEvent` — `{ event: string; data: unknown }`
+- `parseStreamModes(input)` — validate and parse comma-separated mode string
+- `createSSEEncoder()` — `TransformStream<StreamEvent, Uint8Array>` for SSE wire format
+- `sseHeaders()` — standard SSE response headers
+
+### Types
+- `ResourceId` — `{ organizationId?, projectId, userId?, sessionId? }`
+- `Result<T, E>` — discriminated union with `ok()` / `err()` helpers

package/dist/__tests__/shared.test.d.ts

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

package/dist/__tests__/shared.test.js

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

package/dist/cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cache interface for performance optimization.
+ * Extracted from @kognitivedev/core for shared use across all packages.
+ */
+export interface CacheAdapter {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * In-memory cache implementation with TTL support.
+ */
+export declare class InMemoryCacheAdapter implements CacheAdapter {
+    private store;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the cache (including possibly expired).
+     */
+    get size(): number;
+}

package/dist/cache.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryCacheAdapter = void 0;
+/**
+ * In-memory cache implementation with TTL support.
+ */
+class InMemoryCacheAdapter {
+    constructor() {
+        this.store = new Map();
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlSeconds) {
+        const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1000 : null;
+        this.store.set(key, { value, expiresAt });
+    }
+    async delete(key) {
+        this.store.delete(key);
+    }
+    /**
+     * Clear all entries from the cache.
+     */
+    clear() {
+        this.store.clear();
+    }
+    /**
+     * Get the number of entries in the cache (including possibly expired).
+     */
+    get size() {
+        return this.store.size;
+    }
+}
+exports.InMemoryCacheAdapter = InMemoryCacheAdapter;

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Base error class for all Kognitive errors.
+ */
+export declare class KognitiveError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+/**
+ * Error that can be retried (transient failures).
+ */
+export declare class RetryableError extends KognitiveError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Input validation error.
+ */
+export declare class ValidationError extends KognitiveError {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * Operation timed out.
+ */
+export declare class TimeoutError extends KognitiveError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/**
+ * Resource not found.
+ */
+export declare class NotFoundError extends KognitiveError {
+    constructor(resource: string, id: string);
+}
+/**
+ * Tool approval was denied.
+ */
+export declare class ApprovalDeniedError extends KognitiveError {
+    constructor(toolId: string);
+}

package/dist/errors.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalDeniedError = exports.NotFoundError = exports.TimeoutError = exports.ValidationError = exports.RetryableError = exports.KognitiveError = void 0;
+/**
+ * Base error class for all Kognitive errors.
+ */
+class KognitiveError extends Error {
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "KognitiveError";
+    }
+}
+exports.KognitiveError = KognitiveError;
+/**
+ * Error that can be retried (transient failures).
+ */
+class RetryableError extends KognitiveError {
+    constructor(message, cause) {
+        super(message, "RETRYABLE", cause);
+        this.name = "RetryableError";
+    }
+}
+exports.RetryableError = RetryableError;
+/**
+ * Input validation error.
+ */
+class ValidationError extends KognitiveError {
+    constructor(message, field) {
+        super(message, "VALIDATION");
+        this.field = field;
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Operation timed out.
+ */
+class TimeoutError extends KognitiveError {
+    constructor(message, timeoutMs) {
+        super(message, "TIMEOUT");
+        this.timeoutMs = timeoutMs;
+        this.name = "TimeoutError";
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Resource not found.
+ */
+class NotFoundError extends KognitiveError {
+    constructor(resource, id) {
+        super(`${resource} not found: ${id}`, "NOT_FOUND");
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * Tool approval was denied.
+ */
+class ApprovalDeniedError extends KognitiveError {
+    constructor(toolId) {
+        super(`Approval denied for tool: ${toolId}`, "APPROVAL_DENIED");
+        this.name = "ApprovalDeniedError";
+    }
+}
+exports.ApprovalDeniedError = ApprovalDeniedError;

package/dist/events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Typed event bus for decoupled communication between components.
+ * Used for agent lifecycle events, workflow step transitions, tool execution notifications, etc.
+ */
+type EventHandler<T = unknown> = (data: T) => void;
+export interface EventBus {
+    /**
+     * Emit an event with data to all registered handlers.
+     */
+    emit<T>(event: string, data: T): void;
+    /**
+     * Register a handler for an event. Returns an unsubscribe function.
+     */
+    on<T>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Register a one-time handler for an event. Returns an unsubscribe function.
+     */
+    once<T>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Remove all handlers for a specific event, or all events if no event is specified.
+     */
+    removeAll(event?: string): void;
+}
+/**
+ * In-memory event bus implementation.
+ */
+export declare class InMemoryEventBus implements EventBus {
+    private handlers;
+    emit<T>(event: string, data: T): void;
+    on<T>(event: string, handler: EventHandler<T>): () => void;
+    once<T>(event: string, handler: EventHandler<T>): () => void;
+    removeAll(event?: string): void;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Typed event bus for decoupled communication between components.
+ * Used for agent lifecycle events, workflow step transitions, tool execution notifications, etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryEventBus = void 0;
+/**
+ * In-memory event bus implementation.
+ */
+class InMemoryEventBus {
+    constructor() {
+        this.handlers = new Map();
+    }
+    emit(event, data) {
+        const eventHandlers = this.handlers.get(event);
+        if (!eventHandlers)
+            return;
+        for (const handler of eventHandlers) {
+            try {
+                handler(data);
+            }
+            catch (_a) {
+                // Swallow handler errors to prevent breaking the event chain
+            }
+        }
+    }
+    on(event, handler) {
+        if (!this.handlers.has(event)) {
+            this.handlers.set(event, new Set());
+        }
+        const eventHandlers = this.handlers.get(event);
+        eventHandlers.add(handler);
+        return () => {
+            eventHandlers.delete(handler);
+            if (eventHandlers.size === 0) {
+                this.handlers.delete(event);
+            }
+        };
+    }
+    once(event, handler) {
+        const wrappedHandler = (data) => {
+            unsubscribe();
+            handler(data);
+        };
+        const unsubscribe = this.on(event, wrappedHandler);
+        return unsubscribe;
+    }
+    removeAll(event) {
+        if (event) {
+            this.handlers.delete(event);
+        }
+        else {
+            this.handlers.clear();
+        }
+    }
+}
+exports.InMemoryEventBus = InMemoryEventBus;

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { ResourceId, Result, Metadata, Disposable } from "./types";
+export { ok, err } from "./types";
+export type { EventBus } from "./events";
+export { InMemoryEventBus } from "./events";
+export type { Logger } from "./logger";
+export { ConsoleLogger, NoopLogger } from "./logger";
+export type { CacheAdapter } from "./cache";
+export { InMemoryCacheAdapter } from "./cache";
+export { KognitiveError, RetryableError, ValidationError, TimeoutError, NotFoundError, ApprovalDeniedError, } from "./errors";
+export { withRetry, type RetryOptions, type RetryAttempt, type RetryMetadata } from "./utils/retry";
+export { generateId } from "./utils/id";
+export type { SpanLike } from "./telemetry";
+export { createSpan, endSpan, withSpan } from "./telemetry";
+export type { StreamMode, StreamEvent } from "./streaming";
+export { parseStreamModes, createSSEEncoder, sseHeaders } from "./streaming";
+export type { TemplateVariables } from "./template";
+export { renderTemplate } from "./template";

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = exports.sseHeaders = exports.createSSEEncoder = exports.parseStreamModes = exports.withSpan = exports.endSpan = exports.createSpan = exports.generateId = exports.withRetry = exports.ApprovalDeniedError = exports.NotFoundError = exports.TimeoutError = exports.ValidationError = exports.RetryableError = exports.KognitiveError = exports.InMemoryCacheAdapter = exports.NoopLogger = exports.ConsoleLogger = exports.InMemoryEventBus = exports.err = exports.ok = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "ok", { enumerable: true, get: function () { return types_1.ok; } });
+Object.defineProperty(exports, "err", { enumerable: true, get: function () { return types_1.err; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "InMemoryEventBus", { enumerable: true, get: function () { return events_1.InMemoryEventBus; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "ConsoleLogger", { enumerable: true, get: function () { return logger_1.ConsoleLogger; } });
+Object.defineProperty(exports, "NoopLogger", { enumerable: true, get: function () { return logger_1.NoopLogger; } });
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "InMemoryCacheAdapter", { enumerable: true, get: function () { return cache_1.InMemoryCacheAdapter; } });
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "KognitiveError", { enumerable: true, get: function () { return errors_1.KognitiveError; } });
+Object.defineProperty(exports, "RetryableError", { enumerable: true, get: function () { return errors_1.RetryableError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_1.TimeoutError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "ApprovalDeniedError", { enumerable: true, get: function () { return errors_1.ApprovalDeniedError; } });
+// Utilities
+var retry_1 = require("./utils/retry");
+Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return retry_1.withRetry; } });
+var id_1 = require("./utils/id");
+Object.defineProperty(exports, "generateId", { enumerable: true, get: function () { return id_1.generateId; } });
+var telemetry_1 = require("./telemetry");
+Object.defineProperty(exports, "createSpan", { enumerable: true, get: function () { return telemetry_1.createSpan; } });
+Object.defineProperty(exports, "endSpan", { enumerable: true, get: function () { return telemetry_1.endSpan; } });
+Object.defineProperty(exports, "withSpan", { enumerable: true, get: function () { return telemetry_1.withSpan; } });
+var streaming_1 = require("./streaming");
+Object.defineProperty(exports, "parseStreamModes", { enumerable: true, get: function () { return streaming_1.parseStreamModes; } });
+Object.defineProperty(exports, "createSSEEncoder", { enumerable: true, get: function () { return streaming_1.createSSEEncoder; } });
+Object.defineProperty(exports, "sseHeaders", { enumerable: true, get: function () { return streaming_1.sseHeaders; } });
+var template_1 = require("./template");
+Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });

package/dist/logger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Logger interface for structured logging and observability.
+ * Extracted from @kognitivedev/core for shared use across all packages.
+ */
+export interface Logger {
+    debug(message: string, data?: Record<string, any>): void;
+    info(message: string, data?: Record<string, any>): void;
+    warn(message: string, data?: Record<string, any>): void;
+    error(message: string, error?: Error, data?: Record<string, any>): void;
+}
+/**
+ * Default console logger implementation.
+ */
+export declare class ConsoleLogger implements Logger {
+    private prefix;
+    constructor(prefix?: string);
+    debug(message: string, data?: Record<string, any>): void;
+    info(message: string, data?: Record<string, any>): void;
+    warn(message: string, data?: Record<string, any>): void;
+    error(message: string, error?: Error, data?: Record<string, any>): void;
+}
+/**
+ * Silent logger that discards all output. Useful for testing.
+ */
+export declare class NoopLogger implements Logger {
+    debug(_message: string, _data?: Record<string, any>): void;
+    info(_message: string, _data?: Record<string, any>): void;
+    warn(_message: string, _data?: Record<string, any>): void;
+    error(_message: string, _error?: Error, _data?: Record<string, any>): void;
+}

package/dist/logger.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopLogger = exports.ConsoleLogger = void 0;
+/**
+ * Default console logger implementation.
+ */
+class ConsoleLogger {
+    constructor(prefix = "[Kognitive]") {
+        this.prefix = prefix;
+    }
+    debug(message, data) {
+        console.debug(`${this.prefix} DEBUG: ${message}`, data || "");
+    }
+    info(message, data) {
+        console.info(`${this.prefix} INFO: ${message}`, data || "");
+    }
+    warn(message, data) {
+        console.warn(`${this.prefix} WARN: ${message}`, data || "");
+    }
+    error(message, error, data) {
+        console.error(`${this.prefix} ERROR: ${message}`, error, data || "");
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+/**
+ * Silent logger that discards all output. Useful for testing.
+ */
+class NoopLogger {
+    debug(_message, _data) { }
+    info(_message, _data) { }
+    warn(_message, _data) { }
+    error(_message, _error, _data) { }
+}
+exports.NoopLogger = NoopLogger;

package/dist/streaming.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+export type StreamMode = "values" | "updates" | "messages" | "custom" | "debug";
+export interface StreamEvent {
+    /** SSE event name */
+    event: string;
+    /** JSON-serializable payload */
+    data: unknown;
+}
+/**
+ * Parse and validate stream modes from a comma-separated string or array.
+ * Returns ["messages"] if input is empty/undefined (default mode).
+ */
+export declare function parseStreamModes(input: string | string[] | undefined): StreamMode[];
+/**
+ * TransformStream that encodes StreamEvents into SSE wire format.
+ *
+ * Output format per event:
+ *   event: <event>\n
+ *   data: <JSON>\n
+ *   \n
+ */
+export declare function createSSEEncoder(): TransformStream<StreamEvent, Uint8Array>;
+/**
+ * Create SSE Response headers.
+ */
+export declare function sseHeaders(): Record<string, string>;