@cuylabs/agent-core 4.8.1 → 4.10.0

package/dist/events/event-bus/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * EventBus — channel-based event streaming interface.
+ *
+ * Defines how events are published and consumed in a channel-keyed
+ * pub/sub model. The default implementation (`createEventBus`) is
+ * in-process with history replay. A distributed runtime can supply
+ * its own implementation that bridges to external infrastructure
+ * (e.g. Dapr pub/sub, Redis Streams, Kafka).
+ *
+ * Each channel is typically a session ID or workflow instance ID.
+ * Events flow from producers (workflow activities, agent execution)
+ * to consumers (SSE endpoints, WebSocket connections, TUI renderers).
+ */
+export interface EventBusMessage {
+    /** Channel this message was published to. */
+    channel: string;
+    /** Event type — matches AgentEvent.type for agent events. */
+    type: string;
+    /** Serializable event payload. */
+    data: unknown;
+    /** Monotonically increasing sequence within the channel. */
+    seq: number;
+}
+export interface EventBusSubscription {
+    /** Async iterator that yields events as they arrive. */
+    [Symbol.asyncIterator](): AsyncIterableIterator<EventBusMessage>;
+    /** Stop receiving events. Safe to call multiple times. */
+    unsubscribe(): void;
+}
+export interface EventBusSubscribeOptions {
+    /**
+     * Replay messages strictly after this sequence number.
+     * Used to implement SSE resume via `Last-Event-ID`.
+     */
+    afterSeq?: number;
+}
+export interface EventBusOptions {
+    /**
+     * Maximum retained messages per channel for replay.
+     * Older messages are dropped from the head of the history buffer.
+     */
+    maxHistoryMessages?: number;
+    /**
+     * Maximum buffered live messages per subscriber before the subscriber
+     * is disconnected to avoid unbounded memory growth.
+     */
+    maxBufferedMessages?: number;
+    /**
+     * How long (ms) to retain channel history with no active subscribers
+     * so reconnecting clients can resume after transient disconnects.
+     */
+    channelRetentionMs?: number;
+}
+export interface EventBus {
+    /**
+     * Publish an event to all subscribers of `channel`.
+     * Non-blocking — if no one is listening the event is still retained
+     * in the channel history for replay.
+     */
+    publish(channel: string, type: string, data: unknown): void;
+    /**
+     * Subscribe to events on `channel`. Returns an async iterable that
+     * yields events as they arrive and completes when `close(channel)` is
+     * called or the subscription is unsubscribed.
+     */
+    subscribe(channel: string, options?: EventBusSubscribeOptions): EventBusSubscription;
+    /**
+     * Close a channel. All active subscriptions complete their iterators.
+     * Subsequent publishes to this channel start a fresh stream.
+     */
+    close(channel: string, finalEvent?: {
+        type: string;
+        data: unknown;
+    }): void;
+    /** Number of active channels (channels with at least one subscriber). */
+    readonly activeChannels: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/events/event-bus/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/events/event-bus/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;CACb;AAMD,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,eAAe,CAAC,CAAC;IACjE,0DAA0D;IAC1D,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAAC;IAExB;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAE3E,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC"}

package/dist/events/index.d.ts

@@ -1,93 +1,14 @@
 /**
- * EventBus — channel-based event streaming interface.
+ * Event primitives for agent runtimes.
  *
- * Defines how events are published and consumed in a channel-keyed
- * pub/sub model. The default implementation (`createEventBus`) is
- * in-process with history replay. A distributed runtime can supply
- * its own implementation that bridges to external infrastructure
- * (e.g. Dapr pub/sub, Redis Streams, Kafka).
+ * - `AgentSignal` / `LocalSignal`: per-agent, typed, in-process event fan-out.
+ * - `EventBus` / `createEventBus`: channel-based async event streaming with
+ *   replay and backpressure for SSE, WebSocket, and distributed runtimes.
  *
- * Each channel is typically a session ID or workflow instance ID.
- * Events flow from producers (workflow activities, agent execution)
- * to consumers (SSE endpoints, WebSocket connections, TUI renderers).
+ * @module
  */
-interface EventBusMessage {
-    /** Channel this message was published to. */
-    channel: string;
-    /** Event type — matches AgentEvent.type for agent events. */
-    type: string;
-    /** Serializable event payload. */
-    data: unknown;
-    /** Monotonically increasing sequence within the channel. */
-    seq: number;
-}
-interface EventBusSubscription {
-    /** Async iterator that yields events as they arrive. */
-    [Symbol.asyncIterator](): AsyncIterableIterator<EventBusMessage>;
-    /** Stop receiving events. Safe to call multiple times. */
-    unsubscribe(): void;
-}
-interface EventBusSubscribeOptions {
-    /**
-     * Replay messages strictly after this sequence number.
-     * Used to implement SSE resume via `Last-Event-ID`.
-     */
-    afterSeq?: number;
-}
-interface EventBusOptions {
-    /**
-     * Maximum retained messages per channel for replay.
-     * Older messages are dropped from the head of the history buffer.
-     */
-    maxHistoryMessages?: number;
-    /**
-     * Maximum buffered live messages per subscriber before the subscriber
-     * is disconnected to avoid unbounded memory growth.
-     */
-    maxBufferedMessages?: number;
-    /**
-     * How long (ms) to retain channel history with no active subscribers
-     * so reconnecting clients can resume after transient disconnects.
-     */
-    channelRetentionMs?: number;
-}
-interface EventBus {
-    /**
-     * Publish an event to all subscribers of `channel`.
-     * Non-blocking — if no one is listening the event is still retained
-     * in the channel history for replay.
-     */
-    publish(channel: string, type: string, data: unknown): void;
-    /**
-     * Subscribe to events on `channel`. Returns an async iterable that
-     * yields events as they arrive and completes when `close(channel)` is
-     * called or the subscription is unsubscribed.
-     */
-    subscribe(channel: string, options?: EventBusSubscribeOptions): EventBusSubscription;
-    /**
-     * Close a channel. All active subscriptions complete their iterators.
-     * Subsequent publishes to this channel start a fresh stream.
-     */
-    close(channel: string, finalEvent?: {
-        type: string;
-        data: unknown;
-    }): void;
-    /** Number of active channels (channels with at least one subscriber). */
-    readonly activeChannels: number;
-}
-
-/**
- * In-process EventBus implementation.
- *
- * Events are published by producers and consumed by subscribers via
- * async iterators. Each channel maintains a history buffer for replay
- * (e.g. SSE `Last-Event-ID` resume). Channels are automatically
- * cleaned up after a configurable retention period with no subscribers.
- */
-
-/**
- * Create a new in-process event bus.
- */
-declare function createEventBus(options?: EventBusOptions): EventBus;
-
-export { type EventBus, type EventBusMessage, type EventBusOptions, type EventBusSubscribeOptions, type EventBusSubscription, createEventBus };
+export type { AgentSignal } from "./signal/index.js";
+export { LocalSignal } from "./signal/index.js";
+export type { EventBus, EventBusMessage, EventBusOptions, EventBusSubscribeOptions, EventBusSubscription, } from "./event-bus/index.js";
+export { createEventBus } from "./event-bus/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,YAAY,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/events/index.js

@@ -1,6 +1,11 @@
+import "../chunk-3NBTQHVV.js";
 import {
   createEventBus
-} from "../chunk-2TTOLHBT.js";
+} from "../chunk-CFBSQLP5.js";
+import {
+  LocalSignal
+} from "../chunk-UG5PVNZV.js";
 export {
+  LocalSignal,
   createEventBus
 };

package/dist/events/signal/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Signal — typed multi-consumer event dispatch for agent-core.
+ *
+ * @example
+ * ```ts
+ * import { createAgent, LocalSignal } from "@cuylabs/agent-core";
+ *
+ * const agent = createAgent({ model, signal: new LocalSignal() });
+ *
+ * // Subscribe before kicking off a chat
+ * const off = agent.signal.on("text-delta", (e) => process.stdout.write(e.text));
+ * await agent.send("s1", "hello");
+ * off();
+ * ```
+ */
+export type { AgentSignal } from "./types.js";
+export { LocalSignal } from "./local.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/events/signal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/events/signal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/events/signal/index.js

@@ -0,0 +1,6 @@
+import {
+  LocalSignal
+} from "../../chunk-UG5PVNZV.js";
+export {
+  LocalSignal
+};

package/dist/events/signal/local.d.ts

@@ -0,0 +1,22 @@
+/**
+ * LocalSignal — in-process event dispatch.
+ *
+ * Dispatches events synchronously via direct function calls.
+ * Zero dependencies, zero serialization, zero network.
+ *
+ * Handler errors are caught silently — a broken listener must never
+ * interrupt the agent's streaming pipeline.
+ */
+import type { AgentEvent } from "../../types/events.js";
+import type { AgentSignal, TypedHandler, Unsubscribe, WildcardHandler } from "./types.js";
+export declare class LocalSignal implements AgentSignal {
+    /** type → Set<handler> for typed subscriptions */
+    private readonly typed;
+    /** handlers that receive every event */
+    private readonly wildcard;
+    on<T extends AgentEvent["type"]>(type: T, handler: TypedHandler<T>): Unsubscribe;
+    onAny(handler: WildcardHandler): Unsubscribe;
+    emit(event: AgentEvent): void;
+    clear(): void;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/events/signal/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/events/signal/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EACZ,WAAW,EACX,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAY,YAAW,WAAW;IAC7C,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuD;IAC7E,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD,EAAE,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GACvB,WAAW;IAiBd,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW;IAO5C,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuB7B,KAAK,IAAI,IAAI;CAId"}

package/dist/events/signal/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Agent Signal — typed event dispatch interface.
+ *
+ * Defines how consumers subscribe to {@link AgentEvent}s without being
+ * part of the middleware stack.  Each Agent owns a signal; events are
+ * scoped to that agent instance.
+ *
+ * The default implementation (`LocalSignal`) dispatches in-process via
+ * plain function calls.  A distributed runtime can supply its own
+ * implementation that bridges to external infrastructure.
+ */
+import type { AgentEvent } from "../../types/events.js";
+/**
+ * Extract a single variant from the AgentEvent union by its `type` tag.
+ */
+export type EventOf<T extends AgentEvent["type"]> = Extract<AgentEvent, {
+    type: T;
+}>;
+/** Handler for a specific event type. */
+export type TypedHandler<T extends AgentEvent["type"]> = (event: EventOf<T>) => void;
+/** Handler that receives every event regardless of type. */
+export type WildcardHandler = (event: AgentEvent) => void;
+/** Call to remove a previously registered handler. */
+export type Unsubscribe = () => void;
+/**
+ * Typed, multi-consumer event dispatch.
+ *
+ * Subscribe to agent events from anywhere — SSE routes, TUI renderers,
+ * plugins, tests.  The interface is deliberately minimal so that backend
+ * implementations (in-process, Dapr, Redis, …) have a small contract to
+ * fulfil.
+ *
+ * @example
+ * ```ts
+ * // Subscribe to a specific event
+ * const off = agent.signal.on("text-delta", (e) => process.stdout.write(e.text));
+ *
+ * // Subscribe to everything
+ * const off2 = agent.signal.onAny((e) => logger.info(e.type));
+ *
+ * // Clean up
+ * off();
+ * off2();
+ * ```
+ */
+export interface AgentSignal {
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @returns An unsubscribe function.
+     */
+    on<T extends AgentEvent["type"]>(type: T, handler: TypedHandler<T>): Unsubscribe;
+    /**
+     * Subscribe to all events.
+     *
+     * @returns An unsubscribe function.
+     */
+    onAny(handler: WildcardHandler): Unsubscribe;
+    /**
+     * Dispatch an event to every matching handler.
+     *
+     * Called internally by the Agent — but nothing prevents external code
+     * from injecting a synthetic event (useful for testing or bridging).
+     */
+    emit(event: AgentEvent): void;
+    /** Remove all handlers.  Called during agent disposal. */
+    clear(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/events/signal/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/events/signal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,IAAI,OAAO,CACzD,UAAU,EACV;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CACZ,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,IAAI,CACvD,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KACd,IAAI,CAAC;AAEV,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAE1D,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GACvB,WAAW,CAAC;IAEf;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CAAC;IAE7C;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAE9B,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAAC;CACf"}