@nebulaos/client 0.1.0

package/README.md

@@ -0,0 +1,4 @@
+# @nebulaos/client
+
+SDK que conecta o Core ao Server do NebulaOS.
+

package/dist/index.d.mts

@@ -0,0 +1,629 @@
+import { BaseAgent, Workflow, Tool, LogLevel, ILogger, ITracingProvider, SpanStartInput, ActiveSpan, TracingContext, IDomainEventsExporter, NebulaEvent } from '@nebulaos/core';
+import { z } from 'zod';
+import { IHttpClient, ITelemetryExporter, TelemetryEventV1, IMemory, HttpResponse } from '@nebulaos/types';
+export { HttpResponse, IHttpClient } from '@nebulaos/types';
+import { Socket } from 'socket.io-client';
+
+/**
+ * Factory function that creates a new agent instance.
+ * Used to avoid memory/context leakage between executions.
+ */
+type AgentFactory = () => BaseAgent;
+/**
+ * Input that can be either an agent instance (backwards compat) or a factory function.
+ */
+type AgentOrFactory = BaseAgent | AgentFactory;
+declare class Registry {
+    private readonly agentsById;
+    private readonly agentsByName;
+    private readonly workflows;
+    private readonly toolsById;
+    private httpClient?;
+    /**
+     * Sets the HTTP client to be injected into agents for tool execution.
+     */
+    setHttpClient(client: IHttpClient): void;
+    /**
+     * Registers an agent factory or instance.
+     *
+     * If an instance is passed directly (backwards compatibility), it will be wrapped
+     * in a factory that always returns the same instance. For proper isolation between
+     * executions, prefer passing a factory function.
+     *
+     * @param agentOrFactory - Agent instance or factory function
+     */
+    registerAgent(agentOrFactory: AgentOrFactory): void;
+    registerWorkflow(workflow: Workflow): void;
+    registerTool(tool: Tool): void;
+    /**
+     * Gets a new agent instance by id or name.
+     *
+     * Each call creates a fresh instance via the registered factory,
+     * ensuring no memory/context leakage between executions.
+     *
+     * @param idOrName - Agent id or name
+     * @returns A new agent instance
+     */
+    getAgent(idOrName: string): BaseAgent;
+    getWorkflow(id: string): Workflow;
+    getTool(id: string): Tool;
+    /**
+     * Lists all registered agents by creating a sample instance of each.
+     *
+     * Used for Cloud registration where we need agent metadata (name, id, tools, etc).
+     * Creates one instance per agent to extract metadata.
+     *
+     * @returns Array of agent instances (one per registered agent)
+     */
+    listAgents(): BaseAgent[];
+    listTools(): Tool[];
+    listWorkflows(): Workflow[];
+}
+
+declare const serverConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    apiKey: z.ZodString;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+    flushInterval: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    apiKey: string;
+    batchSize?: number | undefined;
+    flushInterval?: number | undefined;
+}, {
+    url: string;
+    apiKey: string;
+    batchSize?: number | undefined;
+    flushInterval?: number | undefined;
+}>;
+type ServerConfig = z.infer<typeof serverConfigSchema>;
+declare const otelTracingConfigSchema: z.ZodObject<{
+    /** OTLP HTTP endpoint. Defaults to http://localhost:4318/v1/traces */
+    otlpEndpoint: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    otlpEndpoint?: string | undefined;
+}, {
+    otlpEndpoint?: string | undefined;
+}>;
+type OTelTracingClientConfig = z.infer<typeof otelTracingConfigSchema>;
+declare const clientConfigSchema: z.ZodObject<{
+    /**
+     * @deprecated clientId is now automatically extracted from the API key.
+     * This field is optional and only used for local identification/logging.
+     */
+    clientId: z.ZodOptional<z.ZodString>;
+    /**
+     * List of agents to register. Can be either:
+     * - Agent instances (backwards compatible, but may cause memory leakage between executions)
+     * - Factory functions that return agent instances (recommended for proper isolation)
+     */
+    agents: z.ZodOptional<z.ZodArray<z.ZodType<AgentOrFactory, z.ZodTypeDef, AgentOrFactory>, "many">>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodType<Tool<any, any>, z.ZodTypeDef, Tool<any, any>>, "many">>;
+    workflows: z.ZodOptional<z.ZodArray<z.ZodType<Workflow<any, any>, z.ZodTypeDef, Workflow<any, any>>, "many">>;
+    server: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        apiKey: z.ZodString;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+        flushInterval: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        apiKey: string;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+    }, {
+        url: string;
+        apiKey: string;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+    }>>;
+    /**
+     * OpenTelemetry tracing configuration.
+     * When set, the client will set up an OTel TracerProvider and export
+     * spans directly to the configured OTLP endpoint.
+     */
+    tracing: z.ZodOptional<z.ZodObject<{
+        /** OTLP HTTP endpoint. Defaults to http://localhost:4318/v1/traces */
+        otlpEndpoint: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        otlpEndpoint?: string | undefined;
+    }, {
+        otlpEndpoint?: string | undefined;
+    }>>;
+    /**
+     * Client-side log level (same semantics as @nebulaos/core ConsoleLogger).
+     * When set to anything other than "none", the client will emit debug logs for
+     * WS/HTTP communication (without full payloads).
+     */
+    logLevel: z.ZodOptional<z.ZodType<LogLevel, z.ZodTypeDef, LogLevel>>;
+    debug: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        level: z.ZodOptional<z.ZodType<LogLevel, z.ZodTypeDef, LogLevel>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        level?: LogLevel | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        level?: LogLevel | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    clientId?: string | undefined;
+    agents?: AgentOrFactory[] | undefined;
+    tools?: Tool<any, any>[] | undefined;
+    workflows?: Workflow<any, any>[] | undefined;
+    server?: {
+        url: string;
+        apiKey: string;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+    } | undefined;
+    tracing?: {
+        otlpEndpoint?: string | undefined;
+    } | undefined;
+    debug?: {
+        enabled?: boolean | undefined;
+        level?: LogLevel | undefined;
+    } | undefined;
+    logLevel?: LogLevel | undefined;
+}, {
+    clientId?: string | undefined;
+    agents?: AgentOrFactory[] | undefined;
+    tools?: Tool<any, any>[] | undefined;
+    workflows?: Workflow<any, any>[] | undefined;
+    server?: {
+        url: string;
+        apiKey: string;
+        batchSize?: number | undefined;
+        flushInterval?: number | undefined;
+    } | undefined;
+    tracing?: {
+        otlpEndpoint?: string | undefined;
+    } | undefined;
+    debug?: {
+        enabled?: boolean | undefined;
+        level?: LogLevel | undefined;
+    } | undefined;
+    logLevel?: LogLevel | undefined;
+}>;
+type ClientConfig = z.infer<typeof clientConfigSchema>;
+
+declare class NebulaClient {
+    private readonly config;
+    private readonly registry;
+    private readonly serverConnection?;
+    private readonly telemetryExporter?;
+    private readonly domainEventsExporter?;
+    private readonly logger?;
+    constructor(config: ClientConfig);
+    registerAgent(agent: Parameters<Registry["registerAgent"]>[0]): void;
+    registerTool(tool: Parameters<Registry["registerTool"]>[0]): void;
+    registerWorkflow(workflow: Parameters<Registry["registerWorkflow"]>[0]): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getClientId(): string | undefined;
+    isConnected(): boolean;
+    /**
+     * Sets global client context for skills to access API key and server URL
+     * This allows skills like RagOpenAISkill to automatically use the client's credentials
+     */
+    private setGlobalClientContext;
+}
+
+declare class TelemetryService {
+}
+
+declare class Batcher {
+}
+
+/**
+ * WebSocket Event Types for NebulaOS Client-Server Communication
+ */
+/**
+ * Resource types supported by the Cloud runtime catalog.
+ */
+type ResourceType = "agent" | "workflow" | "tool";
+/**
+ * Resource registration payload (Cloud RegisterClientDto compatible).
+ */
+interface ResourceRegistration {
+    type: ResourceType;
+    runtimeResourceId: string;
+    displayName: string;
+    kind?: string;
+    description?: string;
+    /**
+     * Optional resource definition (e.g., workflow graph for visualization).
+     */
+    definition?: Record<string, unknown>;
+}
+/**
+ * Payload for full client registration
+ * Note: clientId is now automatically extracted from the API key
+ */
+interface RegisterClientPayload {
+    instanceId: string;
+    resources: ResourceRegistration[];
+}
+/**
+ * Response from client registration
+ */
+interface RegisterResponse {
+    success: boolean;
+    registration?: {
+        clientId: string;
+        instanceId: string;
+    };
+    error?: string;
+}
+/**
+ * Payload for an explicit graceful shutdown notice (best-effort).
+ * Note: clientId is now automatically extracted from the API key
+ */
+interface ShutdownPayload {
+    instanceId: string;
+    reason?: string;
+}
+interface ShutdownResponse {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Base command payload
+ */
+interface BaseCommandPayload {
+    commandId: string;
+    /**
+     * Stable Cloud execution id (Execution.id). Must be echoed back in command responses
+     * and used as telemetry executionId to enable trace lookup by executionId.
+     */
+    executionId: string;
+    type: ResourceType;
+    targetName: string;
+    input: unknown;
+    options?: unknown;
+}
+/**
+ * Agent execution command
+ */
+interface AgentCommandPayload extends BaseCommandPayload {
+    type: "agent";
+}
+/**
+ * Workflow execution command
+ */
+interface WorkflowCommandPayload extends BaseCommandPayload {
+    type: "workflow";
+}
+/**
+ * Tool execution command
+ */
+interface ToolCommandPayload extends BaseCommandPayload {
+    type: "tool";
+}
+/**
+ * Command execution response
+ */
+interface CommandResponse {
+    commandId: string;
+    executionId: string;
+    result: unknown;
+}
+/**
+ * Command execution error
+ */
+interface CommandError {
+    commandId: string;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * WebSocket client-to-server events
+ */
+interface ClientToServerEvents {
+    "client:register:full": (payload: RegisterClientPayload, callback: (response: RegisterResponse) => void) => void;
+    "client:snapshot": (payload: RegisterClientPayload) => void;
+    "client:shutdown": (payload: ShutdownPayload, callback: (response: ShutdownResponse) => void) => void;
+    "command:response": (response: CommandResponse) => void;
+    "command:error": (error: CommandError) => void;
+    "telemetry:batch": (payload: unknown) => void;
+}
+/**
+ * WebSocket server-to-client events
+ */
+interface ServerToClientEvents {
+    "client:online": () => void;
+    "command:execute:agent": (payload: AgentCommandPayload) => void;
+    "command:execute:workflow": (payload: WorkflowCommandPayload) => void;
+    "command:execute:tool": (payload: ToolCommandPayload) => void;
+}
+
+interface ServerConnectionConfig {
+    url: string;
+    apiKey: string;
+    /**
+     * Stable semantic id defined by the developer/runtime deployment.
+     * This value MUST be stable across restarts, otherwise the Cloud will treat it as a new client.
+     */
+    clientId: string;
+    /**
+     * Unique instance identifier for this running process/container/VM.
+     * Defaults to a random UUID if not provided.
+     */
+    instanceId?: string;
+    /**
+     * Optional: snapshot interval for presence/availability refresh.
+     * Defaults to 60 seconds.
+     */
+    snapshotIntervalMs?: number;
+}
+declare class ServerConnection {
+    private readonly config;
+    private socket;
+    private reconnectAttempts;
+    private registry?;
+    private agents;
+    private tools;
+    private workflows;
+    private snapshotTimer?;
+    private connectionAttempted;
+    private lastConnectError;
+    private hasAuthenticated;
+    private readonly logger?;
+    private readonly commandStarts;
+    private readonly clientId;
+    private readonly instanceId;
+    constructor(config: ServerConnectionConfig, logger?: ILogger);
+    /**
+     * Sets the registry for executing agents and workflows.
+     */
+    setRegistry(registry: Registry): void;
+    /**
+     * Stores agents and workflows for registration.
+     */
+    registerResources(agents: BaseAgent[], tools: Tool[], workflows: Workflow[]): void;
+    private collectAgentsFromWorkflows;
+    private collectToolsFromAgents;
+    /**
+     * Creates and configures the Socket.IO client.
+     */
+    private createSocket;
+    /**
+     * Sets up Socket.IO event handlers
+     */
+    private setupEventHandlers;
+    /**
+     * Handles agent execution commands from the server
+     */
+    private handleAgentCommand;
+    /**
+     * Handles workflow execution commands from the server
+     */
+    private handleWorkflowCommand;
+    /**
+     * Handles tool execution commands from the server.
+     */
+    private handleToolCommand;
+    /**
+     * Executes an agent and waits for completion
+     */
+    /**
+     * Sends a successful command response to the server
+     */
+    private sendResponse;
+    /**
+     * Sends an error response to the server
+     */
+    private sendError;
+    /**
+     * Gets the stable ID for an agent (id if available, otherwise name).
+     */
+    private getAgentId;
+    /**
+     * Gets the description from an agent if available.
+     */
+    private getAgentDescription;
+    /**
+     * Builds the Cloud registration payload (RegisterClientDto compatible).
+     */
+    private buildRegisterPayload;
+    private isZodSchema;
+    private isInstructionResolvable;
+    /**
+     * Agent definition payload for Cloud persistence + UI inspection.
+     *
+     * IMPORTANT:
+     * - Do NOT embed tool schemas here; tools are registered as independent resources.
+     * - We only reference tool ids to avoid duplication.
+     */
+    private buildAgentDefinition;
+    /**
+     * Builds a workflow definition payload suitable for Cloud persistence + UI graph rendering.
+     *
+     * The base definition comes from `workflow.describe()` (graph nodes/edges).
+     * If the workflow was created with an input Zod schema, we also attach `inputSchema`
+     * as a JSON Schema object so the UI can render an input form.
+     */
+    private buildWorkflowDefinition;
+    private buildToolDefinition;
+    /**
+     * Full registration (discovery) call. This is idempotent on the Cloud side.
+     */
+    private registerFull;
+    private startSnapshotLoop;
+    /**
+     * Connects to the Cloud runtime.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the server gracefully
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Best-effort shutdown notice to allow the Cloud to immediately clean up instance availability.
+     * Never throws: disconnect must be resilient.
+     */
+    private sendShutdownNotice;
+    /**
+     * Checks if the client is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Returns the client ID
+     */
+    getClientId(): string;
+    getInstanceId(): string;
+    /**
+     * Returns the socket instance for telemetry
+     */
+    getSocket(): Socket<ServerToClientEvents, ClientToServerEvents>;
+}
+
+interface SocketTelemetryExporterConfig {
+    maxBatchSize?: number;
+    flushIntervalMs?: number;
+}
+declare class SocketTelemetryExporter implements ITelemetryExporter {
+    private readonly serverConnection;
+    private readonly config;
+    private readonly queue;
+    private flushTimer;
+    private flushing;
+    constructor(serverConnection: ServerConnection, config?: SocketTelemetryExporterConfig);
+    exportBatch(events: TelemetryEventV1[]): Promise<void>;
+    flush(): Promise<void>;
+    stop(): void;
+    private sendTelemetryBatch;
+    private ensureTimer;
+    private flushIfNeeded;
+}
+
+interface HttpTelemetryExporterConfig {
+    /**
+     * Request timeout for telemetry POSTs (ms).
+     * Telemetry must never block execution, so keep this low.
+     */
+    timeoutMs?: number;
+}
+declare class HttpTelemetryExporter implements ITelemetryExporter {
+    private readonly input;
+    private readonly logger?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(input: {
+        cloudUrl: string;
+        apiKey?: string;
+        clientId: string;
+    }, config?: HttpTelemetryExporterConfig, logger?: ILogger | undefined);
+    exportBatch(events: TelemetryEventV1[]): Promise<void>;
+    private sendSingle;
+}
+
+/**
+ * OpenTelemetry-backed implementation of ITracingProvider.
+ *
+ * OTel internally may represent span/trace IDs in base64 (e.g. when
+ * propagated over binary protocols). This provider normalises every ID
+ * to the W3C hex format expected by the rest of the SDK before handing
+ * them to ActiveSpan / TracingContext.
+ */
+declare class OTelTracingProvider implements ITracingProvider {
+    private readonly exporter;
+    private readonly tracer;
+    constructor(serviceName: string, exporter: ITelemetryExporter);
+    /**
+     * Ensures an OTel ID string is in W3C lowercase hex format.
+     *
+     * If the value is already valid hex of the expected length it is returned
+     * as-is. Otherwise we assume it is base64-encoded and convert it.
+     *
+     * @param id       Raw ID from OTel spanContext()
+     * @param hexLen   Expected hex length (16 for spanId, 32 for traceId)
+     */
+    private ensureW3cHex;
+    startSpan(input: SpanStartInput): ActiveSpan;
+    getContext(): TracingContext | undefined;
+    withSpan<T>(input: SpanStartInput, fn: (span: ActiveSpan) => Promise<T>): Promise<T>;
+}
+
+interface OTelTracingConfig {
+    serviceName: string;
+}
+/**
+ * Sets up the global OTel TracerProvider for context propagation.
+ *
+ * NOTE: The SDK does NOT export spans directly to the collector.
+ * Instead, spans are sent as telemetry events to the backend, which
+ * then exports them to the collector preserving the original spanIds.
+ *
+ * This setup only registers the TracerProvider so that:
+ * - Spans get proper W3C-compliant IDs
+ * - Context propagation works correctly (parent-child relationships)
+ * - trace.getTracer() returns instrumented tracers
+ */
+declare function setupOTelTracing(config: OTelTracingConfig): void;
+
+interface HttpDomainEventsExporterConfig {
+    /**
+     * Request timeout for domain events POSTs (ms).
+     * Domain events must never block execution, so keep this low.
+     */
+    timeoutMs?: number;
+}
+declare class HttpDomainEventsExporter implements IDomainEventsExporter {
+    private readonly input;
+    private readonly logger?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(input: {
+        cloudUrl: string;
+        apiKey?: string;
+        clientId: string;
+    }, config?: HttpDomainEventsExporterConfig, logger?: ILogger | undefined);
+    exportBatch(events: NebulaEvent[]): Promise<void>;
+}
+
+declare class DBMemory implements IMemory {
+    get(_key: string, _sessionId?: string): Promise<unknown>;
+    set(_key: string, _value: unknown, _sessionId?: string, _ttl?: number): Promise<void>;
+    delete(_key: string, _sessionId?: string): Promise<void>;
+    clear(_sessionId?: string): Promise<void>;
+    getHistory(_sessionId: string, _limit?: number): Promise<never[]>;
+}
+
+declare class PromptCapture {
+}
+
+declare class RAGClient {
+}
+
+declare class ClientError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, statusCode?: number, details?: unknown | undefined);
+}
+declare class RegistryError extends ClientError {
+    constructor(message: string, details?: unknown);
+}
+declare class NotFoundError extends ClientError {
+    constructor(entity: "agent" | "workflow" | "tool", id: string);
+}
+declare class AuthenticationError extends ClientError {
+    constructor(message?: string, details?: unknown);
+}
+declare class ConnectionError extends ClientError {
+    constructor(message: string, details?: unknown);
+}
+
+interface HttpRequestOptions extends RequestInit {
+    timeout?: number;
+}
+declare class InstrumentedHttpClient implements IHttpClient {
+    fetch<T = unknown>(url: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+    get<T = unknown>(url: string, options?: Omit<HttpRequestOptions, "method">): Promise<HttpResponse<T>>;
+    post<T = unknown>(url: string, body?: unknown, options?: Omit<HttpRequestOptions, "method" | "body">): Promise<HttpResponse<T>>;
+}
+
+export { type AgentFactory, type AgentOrFactory, AuthenticationError, Batcher, type ClientConfig, ClientError, ConnectionError, DBMemory, HttpDomainEventsExporter, type HttpDomainEventsExporterConfig, type HttpRequestOptions, HttpTelemetryExporter, type HttpTelemetryExporterConfig, InstrumentedHttpClient, NebulaClient, NotFoundError, type OTelTracingClientConfig, type OTelTracingConfig, OTelTracingProvider, PromptCapture, RAGClient, RegistryError, type ServerConfig, SocketTelemetryExporter, type SocketTelemetryExporterConfig, TelemetryService, clientConfigSchema, otelTracingConfigSchema, serverConfigSchema, setupOTelTracing };