@isdk/ai-tool 0.7.1 → 0.8.0

package/dist/{index-DEUnmyUq.d.mts → index-BLW3R7VS.d.mts}

@@ -3,7 +3,6 @@ import { AdvancePropertyManager } from 'property-manager';
 import { AbilityOptions } from 'custom-ability';
 import { CommonError } from '@isdk/common-error';
 import { Cache, ICacheOptions } from 'secondary-cache';
-import { IncomingMessage, ServerResponse } from 'http';
 
 /**
  * Represents the data type of a function parameter as a string (e.g., `'string'`, `'number'`).
@@ -681,9 +680,8 @@ interface RemoteFuncItem extends BaseFuncItem {
      */
     action?: ActionName;
     /**
-     * Options to be passed to the underlying `fetch` call in an HTTP transport.
+     * Addtional options to be passed to the underlying `fetch` call in a transport.
      * @type {any}
-     * @deprecated Use `transport` instead.
      */
     fetchOptions?: any;
 }
@@ -1210,8 +1208,8 @@ declare class ClientTools extends ToolFunc {
     static action?: ActionName | string;
     private static _transport;
     /**
-     * @deprecated This property is now mainly for informational purposes.
-     * The actual endpoint is managed by the transport.
+     * Gets the root URL for API endpoints from the configured transport.
+     * This is used as the base for constructing request URLs.
      */
     static get apiRoot(): string;
     /**
@@ -1234,11 +1232,11 @@ declare class ClientTools extends ToolFunc {
     static loadFromSync(items: Funcs): void;
     static fetch(name: string, objParam?: any, ...args: any[]): Promise<any>;
     /**
-     * @deprecated This property is now mainly for informational purposes.
-     * The actual endpoint is managed by the transport.
+     * Gets the root URL for API endpoints from the configured transport.
+     * This is used as the base for constructing request URLs.
      */
     get apiRoot(): string;
-    fetch(objParam?: any, act?: ActionName, subName?: any): Promise<any>;
+    fetch(objParam?: any, act?: ActionName, subName?: any, fetchOptions?: any): Promise<any>;
     /**
      * The core implementation for a client-side tool. When a `ClientTools` instance
      * is "run", this `func` method is executed. It delegates the call to the
@@ -1391,8 +1389,8 @@ interface RpcMethodsClientFuncParams {
     [name: string]: any;
 }
 declare class RpcMethodsClientTool extends ClientTools {
-    fetch(options: RpcMethodsClientFuncParams, action: ActionName, subName?: any): Promise<any>;
-    _func(action: ActionName, options: RpcMethodsClientFuncParams): Promise<any>;
+    fetch(options: RpcMethodsClientFuncParams, action: ActionName, subName?: any, fetchOptions?: any): Promise<any>;
+    _func(action: ActionName, options: RpcMethodsClientFuncParams, fetchOptions?: any): Promise<any>;
     func(options: RpcMethodsClientFuncParams): Promise<any>;
     assignMethods(methods: string[]): void;
 }
@@ -1414,7 +1412,7 @@ interface ResClientTools {
     list?(options?: ResClientFuncParams): any;
 }
 declare class ResClientTools extends RpcMethodsClientTool {
-    fetch(options: ResClientFuncParams, action: ActionName): Promise<any>;
+    fetch(options: ResClientFuncParams, action: ActionName, ...args: any[]): Promise<any>;
 }
 
 type PubSubCtx<T = any> = {
@@ -1434,6 +1432,12 @@ type PubSubCtx<T = any> = {
  * and managing the connection state.
  */
 interface PubSubClientStream {
+    /**
+     * A unique identifier for this specific stream instance.
+     * This ID is typically generated by the client transport and sent to the
+     * server to establish a stable session identity.
+     */
+    clientId: string;
     /**
      * The protocol being used for this stream (e.g., 'sse', 'ws', 'ipc').
      */
@@ -1491,12 +1495,12 @@ interface PubSubClientStream {
 interface IPubSubClientTransport {
     /**
      * Establishes a connection to a server endpoint.
-     * @param url The URL of the server's PubSub endpoint.
+     * @param url The full URL of the endpoint, or a path relative to the `apiRoot` that may have been configured on the transport.
      * @param params Optional parameters for the connection, which might include
      *   things like authentication tokens, initial subscription topics, or a client ID.
      * @returns A `PubSubClientStream` instance that represents the active connection.
      */
-    connect: (url: string, params?: Record<string, any>) => PubSubClientStream;
+    connect: (url: string, params?: any) => PubSubClientStream | Promise<PubSubClientStream>;
     /**
      * Optional. Disconnects a given stream.
      * While the `close` method exists on the stream itself, placing `disconnect`
@@ -1505,6 +1509,13 @@ interface IPubSubClientTransport {
      * @param stream The stream to disconnect.
      */
     disconnect?: (stream: PubSubClientStream) => void;
+    /**
+     * Optional. Configures the transport with a base URL.
+     * If implemented, this allows the transport to resolve relative paths
+     * passed to the `connect` method.
+     * @param apiRoot The base URL for the API.
+     */
+    setApiRoot?: (apiRoot: string) => void;
 }
 
 /**
@@ -1512,21 +1523,6 @@ interface IPubSubClientTransport {
  * This ID is used for targeted message publishing.
  */
 type PubSubClientId = string;
-/**
- * Represents a client as seen by the transport layer after a subscription is made.
- * It contains the client's ID and can hold other transport-specific metadata.
- */
-interface PubSubClient {
-    /**
-     * The unique identifier for this client.
-     * This can be assigned by the client during connection or generated by the server.
-     */
-    clientId?: PubSubClientId;
-    /**
-     * Allows for storing additional, transport-specific properties about the client.
-     */
-    [k: string]: any;
-}
 /**
  * Represents an active client connection session on the server.
  * This object provides a standardized way for the `EventServer` to interact
@@ -1581,37 +1577,44 @@ interface IPubSubServerTransport {
      */
     readonly protocol: 'sse' | 'ws' | 'ipc' | string;
     /**
-     * Optional method to mount or register the transport's endpoint with an HTTP
-     * server or framework. This is typically required for protocols like SSE or
-     * WebSockets that need to handle incoming HTTP requests at a specific path.
-     *
-     * @param path The URL path to handle (e.g., '/api/events').
-     * @param options Additional options for mounting, specific to the framework.
-     */
-    mount?: (path: string, options?: Record<string, any>) => void;
-    /**
-     * Establishes a connection with a client and subscribes it to an event stream.
+     * Connects a client, establishing a persistent communication channel.
      *
      * This method is designed to be generic. Transport-specific details, such as
-     * HTTP request/response objects or connection handles, should be passed
-     * inside the `options` parameter to avoid polluting the abstraction layer.
+     * HTTP request/response objects, are passed inside the `options` parameter.
+     * For protocols like SSE, initial events can be passed to be subscribed to at connection time.
      *
-     * @param events Optional array of event names to initially subscribe the client to.
-     * @param options A container for transport-specific parameters.
-     * @param options.req The underlying request object (e.g., `http.IncomingMessage`).
-     * @param options.res The underlying response object (e.g., `http.ServerResponse`).
-     * @param options.clientId An optional ID provided by the client. If not provided,
-     *   the transport should generate one.
-     * @param options.headers HTTP headers from the client request.
-     * @returns A `PubSubClient` object representing the newly connected client.
-     */
-    subscribe: (events?: string[], options?: {
-        req?: any;
-        res?: any;
+     * @param options A container for transport-specific parameters, including optional initial events.
+     * @returns A `PubSubServerSession` object representing the newly connected client session.
+     */
+    connect: (options?: {
+        req: any;
+        res: any;
         clientId?: PubSubClientId;
-        headers?: Record<string, string>;
+        events?: string[];
         [k: string]: any;
-    }) => PubSubClient;
+    }) => PubSubServerSession;
+    /**
+     * Subscribes a client session to one or more events.
+     *
+     * Note: Not all transports may support subscribing to new events after the
+     * initial connection. For transports like SSE, this might be a no-op or
+     * throw an error.
+     *
+     * @param session The `PubSubServerSession` of the client.
+     * @param events An array of event names to subscribe to.
+     */
+    subscribe: (session: PubSubServerSession, events: string[]) => void;
+    /**
+     * Unsubscribes a client session from one or more events.
+     *
+     * Note: Not all transports may support unsubscribing from events after the
+     * initial connection. For transports like SSE, this might be a no-op or
+     * throw an error.
+     *
+     * @param session The `PubSubServerSession` of the client.
+     * @param events An array of event names to unsubscribe from.
+     */
+    unsubscribe: (session: PubSubServerSession, events: string[]) => void;
     /**
      * Publishes an event from the server to connected clients.
      *
@@ -1648,6 +1651,14 @@ interface IPubSubServerTransport {
      * @param cb The callback function that receives the session, event name, data, and context.
      */
     onMessage?: (cb: (session: PubSubServerSession, event: string, data: any, ctx?: PubSubCtx) => void) => void;
+    /**
+     * Optional. Finds and returns a session based on a request object.
+     * This is used by higher-level tools to find the correct session
+     * for operations like adding a subscription via a generic RPC call.
+     * @param req The request object (e.g., http.IncomingMessage or Electron.IpcMainEvent).
+     * @returns The corresponding session, or undefined if not found.
+     */
+    getSessionFromReq?: (req: any) => PubSubServerSession | undefined;
 }
 
 interface EventClientFuncParams {
@@ -1664,20 +1675,21 @@ declare class EventClient extends ResClientTools {
     _streamEvents: string[] | undefined;
     _sseListeners: Record<string, (data: any, ctx?: PubSubCtx) => void>;
     _forwardEvents: Set<string>;
-    get evtSource(): PubSubClientStream;
+    get clientId(): string | undefined;
+    getEvtSource(): Promise<PubSubClientStream>;
     get active(): boolean;
-    set active(v: boolean);
+    setActive(v: boolean): Promise<void>;
     description: string;
-    initEventStream(events?: string | string[]): PubSubClientStream;
+    initEventStream(events?: string | string[]): Promise<PubSubClientStream>;
     esListener(evtType: string, data: any, ctx?: PubSubCtx): void;
-    ebListener: (this: Event, ...data: any[]) => Promise<void>;
+    ebListener: (this: Event, ...args: any[]) => Promise<void>;
     /**
-     * subscribe server sent event(SSE)
+     * subscribe server event
      * @param events
      */
     subscribe(events: string | string[]): Promise<any>;
     /**
-     * unsubscribe server sent event(SSE)
+     * unsubscribe server event
      * @param events
      */
     unsubscribe(events: string | string[]): Promise<any>;
@@ -1747,12 +1759,19 @@ declare class ResServerTools extends RpcMethodsServerTool {
     castParams(params: RpcMethodsServerFuncParams): RpcMethodsServerFuncParams;
 }
 
+declare const ClientEventPrefix = "client:";
 interface EventServerFuncParams extends ServerFuncParams {
     event?: string | string[];
     data?: any;
     act?: 'sub' | 'pub' | 'unsub';
+    clientId?: string;
 }
 declare class EventServer extends ResServerTools {
+    /**
+     * Controls whether the client-published events are auto-emitted on server's localBus.
+     * Defaults to false for security. Must be explicitly enabled for 'client:' prefixed events to be emitted.
+     */
+    static autoInjectToLocalBus: boolean;
     private static _boundEbListener?;
     static _pubSubTransport: IPubSubServerTransport | undefined;
     static setPubSubTransport(t?: IPubSubServerTransport): void;
@@ -1763,25 +1782,40 @@ declare class EventServer extends ResServerTools {
         "event-bus": EventToolFunc;
     };
     get pubSubTransport(): IPubSubServerTransport | undefined;
-    static publish(data: any, event: string, target?: {
+    static publish(event: string, data: any, target?: {
         clientId?: string | string[];
     }): void | undefined;
     static ebListener(eventType: string, ...data: any[]): void;
-    static subscribe(req: IncomingMessage, res: ServerResponse, events?: string[], options?: any): PubSubClient | undefined;
     static alreadyForward(event: string): true | undefined;
-    publishSSE(data: any, event: string): any;
-    subscribeSSE(req: IncomingMessage, res: ServerResponse, events?: string | string[]): any;
+    publishServerEvent(event: string, data: any): any;
     forward(events: string | string[]): void;
     unforward(events: string | string[]): void;
-    list({ _req, _res, event }: EventServerFuncParams): void;
-    $sub({ event }: EventServerFuncParams): {
+    list({ _req, _res, event }: EventServerFuncParams): PubSubServerSession;
+    $sub({ event, _req }: EventServerFuncParams): {
+        forward: boolean;
+        subscribed: boolean;
         event: string | string[];
+        clientId: any;
+    } | {
+        forward: boolean;
+        event: string | string[];
+        subscribed?: undefined;
+        clientId?: undefined;
     };
-    $unsub({ event }: EventServerFuncParams): {
+    $unsub({ event, _req }: EventServerFuncParams): {
+        forward: boolean;
+        subscribed: boolean;
+        event: string | string[];
+        clientId: any;
+    } | {
+        forward: boolean;
         event: string | string[];
+        subscribed?: undefined;
+        clientId?: undefined;
     };
-    $publish({ event: events, data }: EventServerFuncParams): {
+    $publish({ event: events, data, _req }: EventServerFuncParams): {
         event: string[];
+        senderId: any;
     };
     isStream(params: ServerFuncParams): boolean;
 }
@@ -1789,4 +1823,4 @@ declare const eventServer: EventServer;
 
 declare function registerCoreTools(): void;
 
-export { funcGetMeta as $, type AsyncTaskId as A, type BinarySemaphoreOptions as B, ClientToolTransport as C, DefaultAsyncSemaphoreCapacity as D, TaskAbortController as E, type Funcs as F, type TaskAbortControllers as G, type TaskPromise as H, type IPubSubServerTransport as I, CancelableAbility as J, makeToolFuncCancelable as K, type FuncParamType as L, type FuncParam as M, type FuncParams as N, type TFunc as O, type PubSubClientId as P, type BaseFuncItem as Q, RemoteToolFuncSchema as R, ServerTools as S, ToolTransport as T, type FuncItem as U, type BaseFunc as V, type ToolFuncPackage as W, ToolFunc as X, ToolFuncSchema as Y, FuncMetaSymbol as Z, funcWithMeta as _, type AIModelNameRules as a, ClientTools as a0, type ClientFuncItem as a1, ClientToolFuncSchema as a2, type ServerFuncParams as a3, type ServerFuncItem as a4, ServerToolFuncSchema as a5, registerCoreTools as a6, EventToolFunc as a7, event as a8, SecondaryCache as a9, _lrucache as aa, createLRUCache as ab, lrucache as ac, type EventClientFuncParams as ad, EventClient as ae, eventClient as af, type EventServerFuncParams as ag, EventServer as ah, eventServer as ai, type RpcMethodsClientFuncParams as aj, RpcMethodsClientTool as ak, RpcMethodsClientToolSchema as al, type RpcMethodsServerFuncParams as am, RpcMethodsServerTool as an, RpcMethodsServerToolSchema as ao, type ResClientFuncParams as ap, ResClientTools as aq, type ResServerFuncParams as ar, ResServerTools as as, type RpcMethodHandler as at, type IClientToolTransport as au, type PubSubCtx as av, type PubSubClient as aw, type PubSubServerSession as b, type IPubSubClientTransport as c, type PubSubClientStream as d, type IToolTransport as e, type ActionName as f, PASSING_SCORE as g, ActionNames as h, type AIModelNameRuleFn as i, type AIModelNameRule as j, type RemoteFuncItem as k, type SemaphoreIsReadyFuncType as l, type BinarySemaphoreAcquireOptions as m, type BinarySemaphoreReleaseOptions as n, type BinarySemaphoreReleaserFunc as o, type SemaphoreOptions as p, type SemaphoreTaskItem as q, BinarySemaphore as r, Semaphore as s, RateLimit as t, ToolAsyncMultiTaskBit as u, ToolAsyncCancelableBit as v, ToolAsyncPriorityBit as w, AsyncFeatureBits as x, AsyncFeatures as y, type CancelableAbilityOptions as z };
+export { funcGetMeta as $, type AsyncTaskId as A, type BinarySemaphoreOptions as B, ClientToolTransport as C, DefaultAsyncSemaphoreCapacity as D, TaskAbortController as E, type Funcs as F, type TaskAbortControllers as G, type TaskPromise as H, type IPubSubServerTransport as I, CancelableAbility as J, makeToolFuncCancelable as K, type FuncParamType as L, type FuncParam as M, type FuncParams as N, type TFunc as O, type PubSubServerSession as P, type BaseFuncItem as Q, RemoteToolFuncSchema as R, ServerTools as S, ToolTransport as T, type FuncItem as U, type BaseFunc as V, type ToolFuncPackage as W, ToolFunc as X, ToolFuncSchema as Y, FuncMetaSymbol as Z, funcWithMeta as _, type AIModelNameRules as a, ClientTools as a0, type ClientFuncItem as a1, ClientToolFuncSchema as a2, type ServerFuncParams as a3, type ServerFuncItem as a4, ServerToolFuncSchema as a5, registerCoreTools as a6, EventToolFunc as a7, event as a8, SecondaryCache as a9, _lrucache as aa, createLRUCache as ab, lrucache as ac, type EventClientFuncParams as ad, EventClient as ae, eventClient as af, ClientEventPrefix as ag, type EventServerFuncParams as ah, EventServer as ai, eventServer as aj, type RpcMethodsClientFuncParams as ak, RpcMethodsClientTool as al, RpcMethodsClientToolSchema as am, type RpcMethodsServerFuncParams as an, RpcMethodsServerTool as ao, RpcMethodsServerToolSchema as ap, type ResClientFuncParams as aq, ResClientTools as ar, type ResServerFuncParams as as, ResServerTools as at, type RpcMethodHandler as au, type IClientToolTransport as av, type PubSubCtx as aw, type PubSubClientId as b, type IPubSubClientTransport as c, type PubSubClientStream as d, type IToolTransport as e, type ActionName as f, PASSING_SCORE as g, ActionNames as h, type AIModelNameRuleFn as i, type AIModelNameRule as j, type RemoteFuncItem as k, type SemaphoreIsReadyFuncType as l, type BinarySemaphoreAcquireOptions as m, type BinarySemaphoreReleaseOptions as n, type BinarySemaphoreReleaserFunc as o, type SemaphoreOptions as p, type SemaphoreTaskItem as q, BinarySemaphore as r, Semaphore as s, RateLimit as t, ToolAsyncMultiTaskBit as u, ToolAsyncCancelableBit as v, ToolAsyncPriorityBit as w, AsyncFeatureBits as x, AsyncFeatures as y, type CancelableAbilityOptions as z };

package/dist/{index-DEUnmyUq.d.ts → index-BLW3R7VS.d.ts}

@@ -3,7 +3,6 @@ import { AdvancePropertyManager } from 'property-manager';
 import { AbilityOptions } from 'custom-ability';
 import { CommonError } from '@isdk/common-error';
 import { Cache, ICacheOptions } from 'secondary-cache';
-import { IncomingMessage, ServerResponse } from 'http';
 
 /**
  * Represents the data type of a function parameter as a string (e.g., `'string'`, `'number'`).
@@ -681,9 +680,8 @@ interface RemoteFuncItem extends BaseFuncItem {
      */
     action?: ActionName;
     /**
-     * Options to be passed to the underlying `fetch` call in an HTTP transport.
+     * Addtional options to be passed to the underlying `fetch` call in a transport.
      * @type {any}
-     * @deprecated Use `transport` instead.
      */
     fetchOptions?: any;
 }
@@ -1210,8 +1208,8 @@ declare class ClientTools extends ToolFunc {
     static action?: ActionName | string;
     private static _transport;
     /**
-     * @deprecated This property is now mainly for informational purposes.
-     * The actual endpoint is managed by the transport.
+     * Gets the root URL for API endpoints from the configured transport.
+     * This is used as the base for constructing request URLs.
      */
     static get apiRoot(): string;
     /**
@@ -1234,11 +1232,11 @@ declare class ClientTools extends ToolFunc {
     static loadFromSync(items: Funcs): void;
     static fetch(name: string, objParam?: any, ...args: any[]): Promise<any>;
     /**
-     * @deprecated This property is now mainly for informational purposes.
-     * The actual endpoint is managed by the transport.
+     * Gets the root URL for API endpoints from the configured transport.
+     * This is used as the base for constructing request URLs.
      */
     get apiRoot(): string;
-    fetch(objParam?: any, act?: ActionName, subName?: any): Promise<any>;
+    fetch(objParam?: any, act?: ActionName, subName?: any, fetchOptions?: any): Promise<any>;
     /**
      * The core implementation for a client-side tool. When a `ClientTools` instance
      * is "run", this `func` method is executed. It delegates the call to the
@@ -1391,8 +1389,8 @@ interface RpcMethodsClientFuncParams {
     [name: string]: any;
 }
 declare class RpcMethodsClientTool extends ClientTools {
-    fetch(options: RpcMethodsClientFuncParams, action: ActionName, subName?: any): Promise<any>;
-    _func(action: ActionName, options: RpcMethodsClientFuncParams): Promise<any>;
+    fetch(options: RpcMethodsClientFuncParams, action: ActionName, subName?: any, fetchOptions?: any): Promise<any>;
+    _func(action: ActionName, options: RpcMethodsClientFuncParams, fetchOptions?: any): Promise<any>;
     func(options: RpcMethodsClientFuncParams): Promise<any>;
     assignMethods(methods: string[]): void;
 }
@@ -1414,7 +1412,7 @@ interface ResClientTools {
     list?(options?: ResClientFuncParams): any;
 }
 declare class ResClientTools extends RpcMethodsClientTool {
-    fetch(options: ResClientFuncParams, action: ActionName): Promise<any>;
+    fetch(options: ResClientFuncParams, action: ActionName, ...args: any[]): Promise<any>;
 }
 
 type PubSubCtx<T = any> = {
@@ -1434,6 +1432,12 @@ type PubSubCtx<T = any> = {
  * and managing the connection state.
  */
 interface PubSubClientStream {
+    /**
+     * A unique identifier for this specific stream instance.
+     * This ID is typically generated by the client transport and sent to the
+     * server to establish a stable session identity.
+     */
+    clientId: string;
     /**
      * The protocol being used for this stream (e.g., 'sse', 'ws', 'ipc').
      */
@@ -1491,12 +1495,12 @@ interface PubSubClientStream {
 interface IPubSubClientTransport {
     /**
      * Establishes a connection to a server endpoint.
-     * @param url The URL of the server's PubSub endpoint.
+     * @param url The full URL of the endpoint, or a path relative to the `apiRoot` that may have been configured on the transport.
      * @param params Optional parameters for the connection, which might include
      *   things like authentication tokens, initial subscription topics, or a client ID.
      * @returns A `PubSubClientStream` instance that represents the active connection.
      */
-    connect: (url: string, params?: Record<string, any>) => PubSubClientStream;
+    connect: (url: string, params?: any) => PubSubClientStream | Promise<PubSubClientStream>;
     /**
      * Optional. Disconnects a given stream.
      * While the `close` method exists on the stream itself, placing `disconnect`
@@ -1505,6 +1509,13 @@ interface IPubSubClientTransport {
      * @param stream The stream to disconnect.
      */
     disconnect?: (stream: PubSubClientStream) => void;
+    /**
+     * Optional. Configures the transport with a base URL.
+     * If implemented, this allows the transport to resolve relative paths
+     * passed to the `connect` method.
+     * @param apiRoot The base URL for the API.
+     */
+    setApiRoot?: (apiRoot: string) => void;
 }
 
 /**
@@ -1512,21 +1523,6 @@ interface IPubSubClientTransport {
  * This ID is used for targeted message publishing.
  */
 type PubSubClientId = string;
-/**
- * Represents a client as seen by the transport layer after a subscription is made.
- * It contains the client's ID and can hold other transport-specific metadata.
- */
-interface PubSubClient {
-    /**
-     * The unique identifier for this client.
-     * This can be assigned by the client during connection or generated by the server.
-     */
-    clientId?: PubSubClientId;
-    /**
-     * Allows for storing additional, transport-specific properties about the client.
-     */
-    [k: string]: any;
-}
 /**
  * Represents an active client connection session on the server.
  * This object provides a standardized way for the `EventServer` to interact
@@ -1581,37 +1577,44 @@ interface IPubSubServerTransport {
      */
     readonly protocol: 'sse' | 'ws' | 'ipc' | string;
     /**
-     * Optional method to mount or register the transport's endpoint with an HTTP
-     * server or framework. This is typically required for protocols like SSE or
-     * WebSockets that need to handle incoming HTTP requests at a specific path.
-     *
-     * @param path The URL path to handle (e.g., '/api/events').
-     * @param options Additional options for mounting, specific to the framework.
-     */
-    mount?: (path: string, options?: Record<string, any>) => void;
-    /**
-     * Establishes a connection with a client and subscribes it to an event stream.
+     * Connects a client, establishing a persistent communication channel.
      *
      * This method is designed to be generic. Transport-specific details, such as
-     * HTTP request/response objects or connection handles, should be passed
-     * inside the `options` parameter to avoid polluting the abstraction layer.
+     * HTTP request/response objects, are passed inside the `options` parameter.
+     * For protocols like SSE, initial events can be passed to be subscribed to at connection time.
      *
-     * @param events Optional array of event names to initially subscribe the client to.
-     * @param options A container for transport-specific parameters.
-     * @param options.req The underlying request object (e.g., `http.IncomingMessage`).
-     * @param options.res The underlying response object (e.g., `http.ServerResponse`).
-     * @param options.clientId An optional ID provided by the client. If not provided,
-     *   the transport should generate one.
-     * @param options.headers HTTP headers from the client request.
-     * @returns A `PubSubClient` object representing the newly connected client.
-     */
-    subscribe: (events?: string[], options?: {
-        req?: any;
-        res?: any;
+     * @param options A container for transport-specific parameters, including optional initial events.
+     * @returns A `PubSubServerSession` object representing the newly connected client session.
+     */
+    connect: (options?: {
+        req: any;
+        res: any;
         clientId?: PubSubClientId;
-        headers?: Record<string, string>;
+        events?: string[];
         [k: string]: any;
-    }) => PubSubClient;
+    }) => PubSubServerSession;
+    /**
+     * Subscribes a client session to one or more events.
+     *
+     * Note: Not all transports may support subscribing to new events after the
+     * initial connection. For transports like SSE, this might be a no-op or
+     * throw an error.
+     *
+     * @param session The `PubSubServerSession` of the client.
+     * @param events An array of event names to subscribe to.
+     */
+    subscribe: (session: PubSubServerSession, events: string[]) => void;
+    /**
+     * Unsubscribes a client session from one or more events.
+     *
+     * Note: Not all transports may support unsubscribing from events after the
+     * initial connection. For transports like SSE, this might be a no-op or
+     * throw an error.
+     *
+     * @param session The `PubSubServerSession` of the client.
+     * @param events An array of event names to unsubscribe from.
+     */
+    unsubscribe: (session: PubSubServerSession, events: string[]) => void;
     /**
      * Publishes an event from the server to connected clients.
      *
@@ -1648,6 +1651,14 @@ interface IPubSubServerTransport {
      * @param cb The callback function that receives the session, event name, data, and context.
      */
     onMessage?: (cb: (session: PubSubServerSession, event: string, data: any, ctx?: PubSubCtx) => void) => void;
+    /**
+     * Optional. Finds and returns a session based on a request object.
+     * This is used by higher-level tools to find the correct session
+     * for operations like adding a subscription via a generic RPC call.
+     * @param req The request object (e.g., http.IncomingMessage or Electron.IpcMainEvent).
+     * @returns The corresponding session, or undefined if not found.
+     */
+    getSessionFromReq?: (req: any) => PubSubServerSession | undefined;
 }
 
 interface EventClientFuncParams {
@@ -1664,20 +1675,21 @@ declare class EventClient extends ResClientTools {
     _streamEvents: string[] | undefined;
     _sseListeners: Record<string, (data: any, ctx?: PubSubCtx) => void>;
     _forwardEvents: Set<string>;
-    get evtSource(): PubSubClientStream;
+    get clientId(): string | undefined;
+    getEvtSource(): Promise<PubSubClientStream>;
     get active(): boolean;
-    set active(v: boolean);
+    setActive(v: boolean): Promise<void>;
     description: string;
-    initEventStream(events?: string | string[]): PubSubClientStream;
+    initEventStream(events?: string | string[]): Promise<PubSubClientStream>;
     esListener(evtType: string, data: any, ctx?: PubSubCtx): void;
-    ebListener: (this: Event, ...data: any[]) => Promise<void>;
+    ebListener: (this: Event, ...args: any[]) => Promise<void>;
     /**
-     * subscribe server sent event(SSE)
+     * subscribe server event
      * @param events
      */
     subscribe(events: string | string[]): Promise<any>;
     /**
-     * unsubscribe server sent event(SSE)
+     * unsubscribe server event
      * @param events
      */
     unsubscribe(events: string | string[]): Promise<any>;
@@ -1747,12 +1759,19 @@ declare class ResServerTools extends RpcMethodsServerTool {
     castParams(params: RpcMethodsServerFuncParams): RpcMethodsServerFuncParams;
 }
 
+declare const ClientEventPrefix = "client:";
 interface EventServerFuncParams extends ServerFuncParams {
     event?: string | string[];
     data?: any;
     act?: 'sub' | 'pub' | 'unsub';
+    clientId?: string;
 }
 declare class EventServer extends ResServerTools {
+    /**
+     * Controls whether the client-published events are auto-emitted on server's localBus.
+     * Defaults to false for security. Must be explicitly enabled for 'client:' prefixed events to be emitted.
+     */
+    static autoInjectToLocalBus: boolean;
     private static _boundEbListener?;
     static _pubSubTransport: IPubSubServerTransport | undefined;
     static setPubSubTransport(t?: IPubSubServerTransport): void;
@@ -1763,25 +1782,40 @@ declare class EventServer extends ResServerTools {
         "event-bus": EventToolFunc;
     };
     get pubSubTransport(): IPubSubServerTransport | undefined;
-    static publish(data: any, event: string, target?: {
+    static publish(event: string, data: any, target?: {
         clientId?: string | string[];
     }): void | undefined;
     static ebListener(eventType: string, ...data: any[]): void;
-    static subscribe(req: IncomingMessage, res: ServerResponse, events?: string[], options?: any): PubSubClient | undefined;
     static alreadyForward(event: string): true | undefined;
-    publishSSE(data: any, event: string): any;
-    subscribeSSE(req: IncomingMessage, res: ServerResponse, events?: string | string[]): any;
+    publishServerEvent(event: string, data: any): any;
     forward(events: string | string[]): void;
     unforward(events: string | string[]): void;
-    list({ _req, _res, event }: EventServerFuncParams): void;
-    $sub({ event }: EventServerFuncParams): {
+    list({ _req, _res, event }: EventServerFuncParams): PubSubServerSession;
+    $sub({ event, _req }: EventServerFuncParams): {
+        forward: boolean;
+        subscribed: boolean;
         event: string | string[];
+        clientId: any;
+    } | {
+        forward: boolean;
+        event: string | string[];
+        subscribed?: undefined;
+        clientId?: undefined;
     };
-    $unsub({ event }: EventServerFuncParams): {
+    $unsub({ event, _req }: EventServerFuncParams): {
+        forward: boolean;
+        subscribed: boolean;
+        event: string | string[];
+        clientId: any;
+    } | {
+        forward: boolean;
         event: string | string[];
+        subscribed?: undefined;
+        clientId?: undefined;
     };
-    $publish({ event: events, data }: EventServerFuncParams): {
+    $publish({ event: events, data, _req }: EventServerFuncParams): {
         event: string[];
+        senderId: any;
     };
     isStream(params: ServerFuncParams): boolean;
 }
@@ -1789,4 +1823,4 @@ declare const eventServer: EventServer;
 
 declare function registerCoreTools(): void;
 
-export { funcGetMeta as $, type AsyncTaskId as A, type BinarySemaphoreOptions as B, ClientToolTransport as C, DefaultAsyncSemaphoreCapacity as D, TaskAbortController as E, type Funcs as F, type TaskAbortControllers as G, type TaskPromise as H, type IPubSubServerTransport as I, CancelableAbility as J, makeToolFuncCancelable as K, type FuncParamType as L, type FuncParam as M, type FuncParams as N, type TFunc as O, type PubSubClientId as P, type BaseFuncItem as Q, RemoteToolFuncSchema as R, ServerTools as S, ToolTransport as T, type FuncItem as U, type BaseFunc as V, type ToolFuncPackage as W, ToolFunc as X, ToolFuncSchema as Y, FuncMetaSymbol as Z, funcWithMeta as _, type AIModelNameRules as a, ClientTools as a0, type ClientFuncItem as a1, ClientToolFuncSchema as a2, type ServerFuncParams as a3, type ServerFuncItem as a4, ServerToolFuncSchema as a5, registerCoreTools as a6, EventToolFunc as a7, event as a8, SecondaryCache as a9, _lrucache as aa, createLRUCache as ab, lrucache as ac, type EventClientFuncParams as ad, EventClient as ae, eventClient as af, type EventServerFuncParams as ag, EventServer as ah, eventServer as ai, type RpcMethodsClientFuncParams as aj, RpcMethodsClientTool as ak, RpcMethodsClientToolSchema as al, type RpcMethodsServerFuncParams as am, RpcMethodsServerTool as an, RpcMethodsServerToolSchema as ao, type ResClientFuncParams as ap, ResClientTools as aq, type ResServerFuncParams as ar, ResServerTools as as, type RpcMethodHandler as at, type IClientToolTransport as au, type PubSubCtx as av, type PubSubClient as aw, type PubSubServerSession as b, type IPubSubClientTransport as c, type PubSubClientStream as d, type IToolTransport as e, type ActionName as f, PASSING_SCORE as g, ActionNames as h, type AIModelNameRuleFn as i, type AIModelNameRule as j, type RemoteFuncItem as k, type SemaphoreIsReadyFuncType as l, type BinarySemaphoreAcquireOptions as m, type BinarySemaphoreReleaseOptions as n, type BinarySemaphoreReleaserFunc as o, type SemaphoreOptions as p, type SemaphoreTaskItem as q, BinarySemaphore as r, Semaphore as s, RateLimit as t, ToolAsyncMultiTaskBit as u, ToolAsyncCancelableBit as v, ToolAsyncPriorityBit as w, AsyncFeatureBits as x, AsyncFeatures as y, type CancelableAbilityOptions as z };
+export { funcGetMeta as $, type AsyncTaskId as A, type BinarySemaphoreOptions as B, ClientToolTransport as C, DefaultAsyncSemaphoreCapacity as D, TaskAbortController as E, type Funcs as F, type TaskAbortControllers as G, type TaskPromise as H, type IPubSubServerTransport as I, CancelableAbility as J, makeToolFuncCancelable as K, type FuncParamType as L, type FuncParam as M, type FuncParams as N, type TFunc as O, type PubSubServerSession as P, type BaseFuncItem as Q, RemoteToolFuncSchema as R, ServerTools as S, ToolTransport as T, type FuncItem as U, type BaseFunc as V, type ToolFuncPackage as W, ToolFunc as X, ToolFuncSchema as Y, FuncMetaSymbol as Z, funcWithMeta as _, type AIModelNameRules as a, ClientTools as a0, type ClientFuncItem as a1, ClientToolFuncSchema as a2, type ServerFuncParams as a3, type ServerFuncItem as a4, ServerToolFuncSchema as a5, registerCoreTools as a6, EventToolFunc as a7, event as a8, SecondaryCache as a9, _lrucache as aa, createLRUCache as ab, lrucache as ac, type EventClientFuncParams as ad, EventClient as ae, eventClient as af, ClientEventPrefix as ag, type EventServerFuncParams as ah, EventServer as ai, eventServer as aj, type RpcMethodsClientFuncParams as ak, RpcMethodsClientTool as al, RpcMethodsClientToolSchema as am, type RpcMethodsServerFuncParams as an, RpcMethodsServerTool as ao, RpcMethodsServerToolSchema as ap, type ResClientFuncParams as aq, ResClientTools as ar, type ResServerFuncParams as as, ResServerTools as at, type RpcMethodHandler as au, type IClientToolTransport as av, type PubSubCtx as aw, type PubSubClientId as b, type IPubSubClientTransport as c, type PubSubClientStream as d, type IToolTransport as e, type ActionName as f, PASSING_SCORE as g, ActionNames as h, type AIModelNameRuleFn as i, type AIModelNameRule as j, type RemoteFuncItem as k, type SemaphoreIsReadyFuncType as l, type BinarySemaphoreAcquireOptions as m, type BinarySemaphoreReleaseOptions as n, type BinarySemaphoreReleaserFunc as o, type SemaphoreOptions as p, type SemaphoreTaskItem as q, BinarySemaphore as r, Semaphore as s, RateLimit as t, ToolAsyncMultiTaskBit as u, ToolAsyncCancelableBit as v, ToolAsyncPriorityBit as w, AsyncFeatureBits as x, AsyncFeatures as y, type CancelableAbilityOptions as z };