@nebulaos/client 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1765 @@
+// src/config/client-config.ts
+import { z } from "zod";
+var serverConfigSchema = z.object({
+  url: z.string().min(1),
+  apiKey: z.string().min(1),
+  batchSize: z.number().int().positive().optional(),
+  flushInterval: z.number().int().positive().optional()
+});
+var otelTracingConfigSchema = z.object({
+  /** OTLP HTTP endpoint. Defaults to http://localhost:4318/v1/traces */
+  otlpEndpoint: z.string().optional()
+});
+var clientConfigSchema = z.object({
+  /**
+   * @deprecated clientId is now automatically extracted from the API key.
+   * This field is optional and only used for local identification/logging.
+   */
+  clientId: z.string().min(1).optional(),
+  /**
+   * 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.array(z.custom()).optional(),
+  tools: z.array(z.custom()).optional(),
+  workflows: z.array(z.custom()).optional(),
+  server: serverConfigSchema.optional(),
+  /**
+   * OpenTelemetry tracing configuration.
+   * When set, the client will set up an OTel TracerProvider and export
+   * spans directly to the configured OTLP endpoint.
+   */
+  tracing: otelTracingConfigSchema.optional(),
+  /**
+   * 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.custom().optional(),
+  // Backwards compatibility (deprecated): prefer `logLevel`.
+  debug: z.object({
+    enabled: z.boolean().optional(),
+    level: z.custom().optional()
+  }).optional()
+});
+
+// src/errors/client-errors.ts
+var ClientError = class extends Error {
+  constructor(message, code, statusCode = 500, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "ClientError";
+  }
+};
+var RegistryError = class extends ClientError {
+  constructor(message, details) {
+    super(message, "REGISTRY_ERROR", 400, details);
+    this.name = "RegistryError";
+  }
+};
+var NotFoundError = class extends ClientError {
+  constructor(entity, id) {
+    super(`${entity} '${id}' not found`, "NOT_FOUND", 404);
+    this.name = "NotFoundError";
+  }
+};
+var AuthenticationError = class extends ClientError {
+  constructor(message = "Authentication failed: Invalid API key or missing credentials", details) {
+    super(message, "AUTHENTICATION_ERROR", 401, details);
+    this.name = "AuthenticationError";
+  }
+};
+var ConnectionError = class extends ClientError {
+  constructor(message, details) {
+    super(message, "CONNECTION_ERROR", 0, details);
+    this.name = "ConnectionError";
+  }
+};
+
+// src/registry/registry.ts
+var Registry = class {
+  agentsById = /* @__PURE__ */ new Map();
+  agentsByName = /* @__PURE__ */ new Map();
+  workflows = /* @__PURE__ */ new Map();
+  toolsById = /* @__PURE__ */ new Map();
+  httpClient;
+  /**
+   * Sets the HTTP client to be injected into agents for tool execution.
+   */
+  setHttpClient(client) {
+    this.httpClient = client;
+  }
+  /**
+   * 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) {
+    let factory;
+    let sampleAgent;
+    if (typeof agentOrFactory === "function") {
+      factory = agentOrFactory;
+      sampleAgent = factory();
+    } else {
+      const instance = agentOrFactory;
+      factory = () => instance;
+      sampleAgent = instance;
+    }
+    const id = "id" in sampleAgent && typeof sampleAgent.id === "string" && sampleAgent.id ? sampleAgent.id : sampleAgent.name;
+    if (this.agentsById.has(id)) {
+      throw new RegistryError(`Agent '${id}' already registered`);
+    }
+    if (this.agentsByName.has(sampleAgent.name)) {
+      throw new RegistryError(`Agent name '${sampleAgent.name}' already registered`);
+    }
+    const entry = {
+      factory,
+      id,
+      name: sampleAgent.name
+    };
+    this.agentsById.set(id, entry);
+    this.agentsByName.set(sampleAgent.name, entry);
+  }
+  registerWorkflow(workflow) {
+    const workflowId = workflow.id;
+    if (!workflowId) {
+      throw new RegistryError("Workflow id is required to register workflow");
+    }
+    if (this.workflows.has(workflowId)) {
+      throw new RegistryError(`Workflow '${workflowId}' already registered`);
+    }
+    this.workflows.set(workflowId, workflow);
+  }
+  registerTool(tool) {
+    const id = tool?.id;
+    if (!id || typeof id !== "string") {
+      throw new RegistryError("Tool id is required to register tool");
+    }
+    if (this.toolsById.has(id)) {
+      throw new RegistryError(`Tool '${id}' already registered`);
+    }
+    this.toolsById.set(id, tool);
+  }
+  /**
+   * 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) {
+    const entry = this.agentsById.get(idOrName) ?? this.agentsByName.get(idOrName);
+    if (!entry) {
+      throw new NotFoundError("agent", idOrName);
+    }
+    const agent = entry.factory();
+    if (this.httpClient && typeof agent.setHttpClient === "function") {
+      agent.setHttpClient(this.httpClient);
+    }
+    return agent;
+  }
+  getWorkflow(id) {
+    const workflow = this.workflows.get(id);
+    if (!workflow) {
+      throw new NotFoundError("workflow", id);
+    }
+    return workflow;
+  }
+  getTool(id) {
+    const tool = this.toolsById.get(id);
+    if (!tool) {
+      throw new NotFoundError("tool", id);
+    }
+    return 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() {
+    return Array.from(this.agentsById.values()).map((entry) => entry.factory());
+  }
+  listTools() {
+    return Array.from(this.toolsById.values());
+  }
+  listWorkflows() {
+    return Array.from(this.workflows.values());
+  }
+};
+
+// src/connection/server-connection.ts
+import { io } from "socket.io-client";
+import { v4 as uuid } from "uuid";
+import { ExecutionContext, Tracing } from "@nebulaos/core";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// src/logger/time.ts
+function nowMs() {
+  const anyGlobal = globalThis;
+  if (anyGlobal?.performance?.now) return anyGlobal.performance.now();
+  return Date.now();
+}
+function durationMs(startMs) {
+  return Math.max(0, nowMs() - startMs);
+}
+
+// src/logger/summaries.ts
+function summarizeValue(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") return `string(len=${value.length})`;
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (Array.isArray(value)) return `array(len=${value.length})`;
+  if (typeof value === "object") return `object(keys=${Object.keys(value).length})`;
+  return typeof value;
+}
+function summarizeDomainEvent(event) {
+  return {
+    type: event.type,
+    executionId: event.executionId,
+    rootExecutionId: event.rootExecutionId,
+    parentExecutionId: event.parentExecutionId,
+    correlationId: event.correlationId,
+    traceId: event.trace?.traceId,
+    spanId: event.trace?.spanId,
+    parentSpanId: event.trace?.parentSpanId
+  };
+}
+function summarizeTelemetryEvent(event) {
+  return {
+    type: event.type,
+    executionId: event.executionId,
+    correlationId: event.correlationId,
+    traceId: event.trace?.traceId,
+    spanId: event.trace?.spanId,
+    parentSpanId: event.trace?.parentSpanId,
+    spanKind: event.span?.kind,
+    spanName: event.span?.name
+  };
+}
+function summarizeDomainBatch(events) {
+  const counts = {};
+  for (const e of events) {
+    counts[e.type] = (counts[e.type] ?? 0) + 1;
+  }
+  const topTypes = Object.entries(counts).sort((a, b) => b[1] - a[1]).slice(0, 6).map(([type, count]) => `${type}\xD7${count}`);
+  return {
+    count: events.length,
+    topTypes: topTypes.join(", ")
+  };
+}
+
+// src/connection/server-connection.ts
+var ServerConnection = class {
+  constructor(config, logger) {
+    this.config = config;
+    this.clientId = config.clientId;
+    this.instanceId = config.instanceId ?? uuid();
+    this.logger = logger;
+    this.socket = this.createSocket();
+  }
+  socket;
+  reconnectAttempts = 0;
+  registry;
+  agents = [];
+  tools = [];
+  workflows = [];
+  snapshotTimer;
+  connectionAttempted = false;
+  lastConnectError = null;
+  hasAuthenticated = false;
+  logger;
+  commandStarts = /* @__PURE__ */ new Map();
+  clientId;
+  instanceId;
+  /**
+   * Sets the registry for executing agents and workflows.
+   */
+  setRegistry(registry) {
+    this.registry = registry;
+  }
+  /**
+   * Stores agents and workflows for registration.
+   */
+  registerResources(agents, tools, workflows) {
+    this.agents = agents;
+    this.tools = tools;
+    this.workflows = workflows;
+  }
+  collectAgentsFromWorkflows() {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const workflow of this.workflows) {
+      const workflowWithNodes = workflow;
+      if (typeof workflowWithNodes.__internalNodes !== "function") continue;
+      const nodes = workflowWithNodes.__internalNodes();
+      if (!Array.isArray(nodes)) continue;
+      for (const node of nodes) {
+        if (node.type !== "agent") continue;
+        const agentNode = node;
+        const agent = agentNode.agent;
+        if (!agent) continue;
+        const id = agent.id ?? agent.name;
+        if (!id) continue;
+        if (seen.has(id)) continue;
+        seen.add(id);
+        out.push(agent);
+      }
+    }
+    return out;
+  }
+  collectToolsFromAgents(agents) {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const agent of agents) {
+      const agentWithConfig = agent;
+      const config = agentWithConfig.config;
+      if (!config || typeof config !== "object") continue;
+      const tools = Array.isArray(config.tools) ? config.tools : [];
+      for (const tool of tools) {
+        if (!tool || typeof tool.id !== "string") continue;
+        if (seen.has(tool.id)) continue;
+        seen.add(tool.id);
+        out.push(tool);
+      }
+    }
+    return out;
+  }
+  /**
+   * Creates and configures the Socket.IO client.
+   */
+  createSocket() {
+    const socket = io(`${this.config.url}/runtime`, {
+      auth: { token: this.config.apiKey },
+      reconnection: true,
+      reconnectionDelay: 1e3,
+      reconnectionDelayMax: 5e3,
+      transports: ["websocket"]
+    });
+    this.setupEventHandlers(socket);
+    return socket;
+  }
+  /**
+   * Sets up Socket.IO event handlers
+   */
+  setupEventHandlers(socket) {
+    socket.on("connect", () => {
+      if (this.logger) {
+        this.logger.info("WS connected", { url: this.config.url, transport: "websocket" });
+      } else {
+        console.log("\u2705 Connected to NebulaOS Cloud");
+      }
+      this.reconnectAttempts = 0;
+      this.lastConnectError = null;
+      this.hasAuthenticated = false;
+    });
+    socket.on("disconnect", (reason) => {
+      if (!this.hasAuthenticated && reason === "io server disconnect") {
+        if (this.logger) {
+          this.logger.error("WS rejected by server (likely auth failure)", { reason });
+        } else {
+          console.error(
+            `\u{1F510} Connection rejected by server (likely authentication failure). Please check your NEBULAOS_API_KEY environment variable. (Reason: ${reason})`
+          );
+        }
+      } else {
+        if (this.logger) {
+          this.logger.warn("WS disconnected", { reason });
+        } else {
+          console.warn(`\u26A0\uFE0F  Disconnected: ${reason}`);
+        }
+      }
+    });
+    socket.on("connect_error", (error) => {
+      this.reconnectAttempts++;
+      this.lastConnectError = error;
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const rawStack = error instanceof Error ? error.stack : void 0;
+      const errorWithData = error;
+      const serverData = errorWithData.data;
+      const serverMessage = typeof serverData?.message === "string" ? serverData.message : typeof serverData?.error === "string" ? serverData.error : void 0;
+      const lower = rawMessage.toLowerCase();
+      const looksLikeAuth = lower.includes("authorization") || lower.includes("token") || lower.includes("unauthorized") || lower.includes("authentication") || lower.includes("api key") || lower.includes("invalid");
+      const meta = {
+        url: this.config.url,
+        attempt: this.reconnectAttempts,
+        serverMessage,
+        serverData,
+        // Preserve raw stack for debugging (dev use)
+        stack: rawStack,
+        hint: looksLikeAuth ? "Looks like auth failure. Check NEBULAOS_API_KEY." : "See error details above (network/DNS/URL/CORS)."
+      };
+      if (this.logger) {
+        this.logger.error(`WS connect_error: ${rawMessage}`, meta);
+      } else {
+        console.error(`\u274C connect_error (attempt ${this.reconnectAttempts}): ${rawMessage}`, meta);
+      }
+    });
+    socket.on("client:online", () => {
+      this.hasAuthenticated = true;
+      if (this.logger) {
+        this.logger.info("WS authenticated (client:online)");
+      }
+      void this.registerFull();
+    });
+    socket.on(
+      "command:execute:agent",
+      (payload) => void this.handleAgentCommand(payload)
+    );
+    socket.on(
+      "command:execute:workflow",
+      (payload) => void this.handleWorkflowCommand(payload)
+    );
+    socket.on(
+      "command:execute:tool",
+      (payload) => void this.handleToolCommand(payload)
+    );
+  }
+  /**
+   * Handles agent execution commands from the server
+   */
+  async handleAgentCommand(payload) {
+    const startedAt = nowMs();
+    this.commandStarts.set(payload.commandId, startedAt);
+    if (this.logger) {
+      this.logger.info("Command received", {
+        type: payload.type,
+        target: payload.targetName,
+        commandId: payload.commandId,
+        executionId: payload.executionId,
+        input: summarizeValue(payload.input)
+      });
+    } else {
+      console.log(`\u{1F4E5} Received agent execution command: ${payload.targetName}`);
+    }
+    if (!this.registry) {
+      this.sendError(payload.commandId, {
+        code: "REGISTRY_NOT_SET",
+        message: "Registry not configured"
+      });
+      return;
+    }
+    try {
+      const agent = this.registry.getAgent(payload.targetName);
+      let agentInput;
+      if (payload.input) {
+        if (typeof payload.input === "string") {
+          agentInput = payload.input;
+        } else if (Array.isArray(payload.input)) {
+          agentInput = payload.input;
+        } else {
+          agentInput = JSON.stringify(payload.input);
+        }
+      }
+      const options = payload.options && typeof payload.options === "object" ? { ...payload.options, executionId: payload.executionId } : { executionId: payload.executionId };
+      const result = await ExecutionContext.run(
+        {
+          executionId: payload.executionId,
+          rootExecutionId: payload.executionId,
+          parentExecutionId: void 0
+        },
+        async () => agent.execute(agentInput, options)
+      );
+      this.sendResponse(payload.commandId, payload.executionId, result);
+      if (this.logger) {
+        this.logger.info("Command handled", {
+          commandId: payload.commandId,
+          executionId: payload.executionId,
+          durationMs: Number(durationMs(startedAt).toFixed(2))
+        });
+      }
+    } catch (error) {
+      this.sendError(payload.commandId, {
+        code: "AGENT_EXECUTION_ERROR",
+        message: error instanceof Error ? error.message : "Unknown error",
+        details: error
+      });
+    }
+  }
+  /**
+   * Handles workflow execution commands from the server
+   */
+  async handleWorkflowCommand(payload) {
+    const startedAt = nowMs();
+    this.commandStarts.set(payload.commandId, startedAt);
+    if (this.logger) {
+      this.logger.info("Command received", {
+        type: payload.type,
+        target: payload.targetName,
+        commandId: payload.commandId,
+        executionId: payload.executionId,
+        input: summarizeValue(payload.input)
+      });
+    } else {
+      console.log(`\u{1F4E5} Received workflow execution command: ${payload.targetName}`);
+    }
+    if (!this.registry) {
+      this.sendError(payload.commandId, {
+        code: "REGISTRY_NOT_SET",
+        message: "Registry not configured"
+      });
+      return;
+    }
+    try {
+      const workflow = this.registry.getWorkflow(payload.targetName);
+      const result = await ExecutionContext.run(
+        {
+          executionId: payload.executionId,
+          rootExecutionId: payload.executionId,
+          parentExecutionId: void 0
+        },
+        async () => workflow.run(
+          payload.input,
+          { executionId: payload.executionId }
+        )
+      );
+      this.sendResponse(payload.commandId, payload.executionId, result);
+      if (this.logger) {
+        this.logger.info("Command handled", {
+          commandId: payload.commandId,
+          executionId: payload.executionId,
+          durationMs: Number(durationMs(startedAt).toFixed(2))
+        });
+      }
+    } catch (error) {
+      this.sendError(payload.commandId, {
+        code: "WORKFLOW_EXECUTION_ERROR",
+        message: error instanceof Error ? error.message : "Unknown error",
+        details: error
+      });
+    }
+  }
+  /**
+   * Handles tool execution commands from the server.
+   */
+  async handleToolCommand(payload) {
+    const startedAt = nowMs();
+    this.commandStarts.set(payload.commandId, startedAt);
+    if (this.logger) {
+      this.logger.info("Command received", {
+        type: payload.type,
+        target: payload.targetName,
+        commandId: payload.commandId,
+        executionId: payload.executionId,
+        input: summarizeValue(payload.input)
+      });
+    } else {
+      console.log(`\u{1F4E5} Received tool execution command: ${payload.targetName}`);
+    }
+    if (!this.registry) {
+      this.sendError(payload.commandId, {
+        code: "REGISTRY_NOT_SET",
+        message: "Registry not configured"
+      });
+      return;
+    }
+    try {
+      const tool = this.registry.getTool(payload.targetName);
+      const result = await ExecutionContext.run(
+        {
+          executionId: payload.executionId,
+          rootExecutionId: payload.executionId,
+          parentExecutionId: void 0
+        },
+        async () => Tracing.withSpan(
+          {
+            kind: "tool",
+            name: `tool:${tool.id}`,
+            executionId: payload.executionId,
+            data: {
+              toolId: tool.id
+            }
+          },
+          async () => {
+            return tool.execute({}, payload.input);
+          }
+        )
+      );
+      this.sendResponse(payload.commandId, payload.executionId, result);
+      if (this.logger) {
+        this.logger.info("Command handled", {
+          commandId: payload.commandId,
+          executionId: payload.executionId,
+          durationMs: Number(durationMs(startedAt).toFixed(2))
+        });
+      }
+    } catch (error) {
+      this.sendError(payload.commandId, {
+        code: "TOOL_EXECUTION_ERROR",
+        message: error instanceof Error ? error.message : "Unknown error",
+        details: error
+      });
+    }
+  }
+  /**
+   * Executes an agent and waits for completion
+   */
+  // NOTE:
+  // We intentionally removed the previous "wait for start event to resolve executionId" logic.
+  // Cloud already provides a stable `payload.executionId` and expects it back in `command:response`.
+  /**
+   * Sends a successful command response to the server
+   */
+  sendResponse(commandId, executionId, result) {
+    const response = {
+      commandId,
+      executionId,
+      result
+    };
+    this.socket.emit("command:response", response);
+    const startedAt = this.commandStarts.get(commandId);
+    if (this.logger) {
+      this.logger.info("Command response sent", {
+        commandId,
+        executionId,
+        durationMs: startedAt ? Number(durationMs(startedAt).toFixed(2)) : void 0,
+        result: summarizeValue(result)
+      });
+    } else {
+      console.log(`\u2705 Sent response for command ${commandId}`);
+    }
+  }
+  /**
+   * Sends an error response to the server
+   */
+  sendError(commandId, error) {
+    const errorResponse = {
+      commandId,
+      error
+    };
+    this.socket.emit("command:error", errorResponse);
+    const startedAt = this.commandStarts.get(commandId);
+    if (this.logger) {
+      this.logger.error("Command error sent", {
+        commandId,
+        durationMs: startedAt ? Number(durationMs(startedAt).toFixed(2)) : void 0,
+        code: error.code,
+        message: error.message
+      });
+    } else {
+      console.error(`\u274C Sent error for command ${commandId}:`, error.message);
+    }
+  }
+  /**
+   * Gets the stable ID for an agent (id if available, otherwise name).
+   */
+  getAgentId(agent) {
+    return agent.id ?? agent.name;
+  }
+  /**
+   * Gets the description from an agent if available.
+   */
+  getAgentDescription(agent) {
+    const agentWithConfig = agent;
+    const config = agentWithConfig.config;
+    if (config && typeof config === "object" && "description" in config) {
+      return typeof config.description === "string" ? config.description : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Builds the Cloud registration payload (RegisterClientDto compatible).
+   */
+  async buildRegisterPayload(input) {
+    const workflowAgents = this.collectAgentsFromWorkflows();
+    const agents = [...this.agents];
+    for (const agent of workflowAgents) {
+      const id = this.getAgentId(agent);
+      const exists = agents.some((x) => this.getAgentId(x) === id);
+      if (!exists) agents.push(agent);
+    }
+    const agentTools = this.collectToolsFromAgents(agents);
+    const tools = [...this.tools];
+    for (const tool of agentTools) {
+      if (tools.some((x) => x.id === tool.id)) continue;
+      tools.push(tool);
+    }
+    const resources = [
+      ...agents.map((agent) => {
+        const runtimeResourceId = this.getAgentId(agent);
+        const description = this.getAgentDescription(agent);
+        return {
+          type: "agent",
+          runtimeResourceId,
+          displayName: agent.name,
+          kind: agent.kind,
+          description
+        };
+      }),
+      ...this.workflows.map((workflow) => {
+        const definition = input.includeDefinitions ? this.buildWorkflowDefinition(workflow) : void 0;
+        return {
+          type: "workflow",
+          runtimeResourceId: workflow.id,
+          displayName: workflow.name ?? workflow.id,
+          description: workflow.description,
+          ...definition ? { definition } : {}
+        };
+      }),
+      ...tools.map((tool) => {
+        const definition = input.includeDefinitions ? this.buildToolDefinition(tool) : void 0;
+        return {
+          type: "tool",
+          runtimeResourceId: tool.id,
+          displayName: tool.id,
+          description: tool.description,
+          ...definition ? { definition } : {}
+        };
+      })
+    ];
+    if (input.includeDefinitions) {
+      await Promise.all(
+        resources.filter((r) => r.type === "agent").map(async (r) => {
+          const agent = agents.find((a) => this.getAgentId(a) === r.runtimeResourceId);
+          if (!agent) return;
+          const def = await this.buildAgentDefinition(agent);
+          if (def) r.definition = def;
+        })
+      );
+    }
+    return {
+      instanceId: this.instanceId,
+      // Dedupe by (type + runtimeResourceId) to avoid duplicates when tools are discovered from multiple sources.
+      resources: resources.filter((r, idx, arr) => {
+        const key = `${r.type}:${r.runtimeResourceId}`;
+        return idx === arr.findIndex((x) => `${x.type}:${x.runtimeResourceId}` === key);
+      })
+    };
+  }
+  isZodSchema(value) {
+    return !!value && typeof value === "object" && "safeParse" in value && typeof value.safeParse === "function";
+  }
+  isInstructionResolvable(value) {
+    return !!value && typeof value === "object" && "resolve" in value && typeof value.resolve === "function";
+  }
+  /**
+   * 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.
+   */
+  async buildAgentDefinition(agent) {
+    const agentWithConfig = agent;
+    const config = agentWithConfig.config;
+    if (!config || typeof config !== "object") return void 0;
+    const model = config.model;
+    const instructions = config.instructions;
+    const tools = Array.isArray(config.tools) ? config.tools : [];
+    const interceptors = config.interceptors;
+    let instructionsText = "";
+    if (typeof instructions === "string") {
+      instructionsText = instructions;
+    } else if (this.isInstructionResolvable(instructions)) {
+      instructionsText = await instructions.resolve();
+    }
+    const requestInterceptorNames = interceptors?.request?.map((fn) => {
+      if (typeof fn === "function" && fn.name) {
+        return fn.name;
+      }
+      return "anonymous";
+    }) ?? [];
+    const responseInterceptorNames = interceptors?.response?.map((fn) => {
+      if (typeof fn === "function" && fn.name) {
+        return fn.name;
+      }
+      return "anonymous";
+    }) ?? [];
+    const modelInfo = model && typeof model === "object" && "providerName" in model && "modelName" in model ? {
+      provider: model.providerName,
+      model: model.modelName,
+      capabilities: model.capabilities
+    } : void 0;
+    return {
+      schemaVersion: 1,
+      resourceType: "agent",
+      agentId: agent.id ?? agent.name,
+      agentName: agent.name,
+      kind: agent.kind,
+      model: modelInfo,
+      instructionsText,
+      toolIds: tools.map((t) => t.id),
+      interceptors: {
+        request: requestInterceptorNames,
+        response: responseInterceptorNames
+      }
+    };
+  }
+  /**
+   * 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.
+   */
+  buildWorkflowDefinition(workflow) {
+    const workflowWithNodes = workflow;
+    if (typeof workflowWithNodes.describe !== "function") return void 0;
+    const base = workflowWithNodes.describe();
+    if (!base || typeof base !== "object") return void 0;
+    const workflowUnknown = workflow;
+    const workflowWithConfig = workflowUnknown && typeof workflowUnknown === "object" && "config" in workflowUnknown && typeof workflowUnknown.config === "object" ? workflowUnknown.config?.inputSchema : void 0;
+    const inputSchemaCandidate = workflowWithConfig;
+    const withSchemas = this.isZodSchema(inputSchemaCandidate) ? { ...base, inputSchema: zodToJsonSchema(inputSchemaCandidate) } : base;
+    const nodes = Array.isArray(withSchemas.nodes) ? withSchemas.nodes : void 0;
+    const agentIds = Array.isArray(nodes) ? nodes.map((n) => typeof n?.agentId === "string" && n.agentId ? n.agentId : void 0).filter((x) => !!x) : [];
+    return {
+      ...withSchemas,
+      schemaVersion: 1,
+      resourceType: "workflow",
+      refs: {
+        agents: Array.from(new Set(agentIds)),
+        tools: [],
+        workflows: []
+      }
+    };
+  }
+  buildToolDefinition(tool) {
+    const inputSchemaCandidate = tool.inputSchema;
+    const inputSchema = this.isZodSchema(inputSchemaCandidate) ? zodToJsonSchema(inputSchemaCandidate) : void 0;
+    return {
+      schemaVersion: 1,
+      resourceType: "tool",
+      toolId: tool.id,
+      description: tool.description,
+      ...inputSchema ? { inputSchema } : {},
+      outputType: "unknown"
+    };
+  }
+  /**
+   * Full registration (discovery) call. This is idempotent on the Cloud side.
+   */
+  async registerFull() {
+    const payload = await this.buildRegisterPayload({ includeDefinitions: true });
+    const start = nowMs();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(
+          new ConnectionError(
+            "Registration timeout: Server did not respond to registration request. Please check your connection and try again."
+          )
+        );
+      }, 1e4);
+      this.socket.emit("client:register:full", payload, (response) => {
+        clearTimeout(timeout);
+        if (response.success) {
+          const defCount = payload.resources.filter((r) => !!r.definition).length;
+          const agentDefCount = payload.resources.filter(
+            (r) => r.type === "agent" && !!r.definition
+          ).length;
+          const workflowDefCount = payload.resources.filter(
+            (r) => r.type === "workflow" && !!r.definition
+          ).length;
+          const toolDefCount = payload.resources.filter(
+            (r) => r.type === "tool" && !!r.definition
+          ).length;
+          if (this.logger) {
+            this.logger.info("Client registered", {
+              clientId: this.clientId,
+              instanceId: payload.instanceId,
+              resources: payload.resources.length,
+              definitions: {
+                total: defCount,
+                agents: agentDefCount,
+                workflows: workflowDefCount,
+                tools: toolDefCount
+              },
+              durationMs: Number(durationMs(start).toFixed(2))
+            });
+          } else {
+            console.log(
+              `\u2705 Client registered successfully: ${this.clientId} (${payload.instanceId})`
+            );
+            console.log(`   - ${payload.resources.length} resources registered`);
+            console.log(
+              `   - definitions: total=${defCount}, agents=${agentDefCount}, workflows=${workflowDefCount}, tools=${toolDefCount}`
+            );
+          }
+          resolve();
+          return;
+        }
+        const errorMessage = response.error ?? "Unknown registration error";
+        if (errorMessage.includes("authentication") || errorMessage.includes("Unauthorized") || errorMessage.includes("token") || errorMessage.includes("API key")) {
+          reject(
+            new AuthenticationError(
+              `Registration failed: ${errorMessage}. Please check your NEBULAOS_API_KEY environment variable.`
+            )
+          );
+          return;
+        }
+        reject(
+          new ConnectionError(
+            `Registration failed: ${errorMessage}. Please check your connection and configuration.`
+          )
+        );
+      });
+    });
+  }
+  startSnapshotLoop() {
+    const intervalMs = this.config.snapshotIntervalMs ?? 6e4;
+    if (this.snapshotTimer) clearInterval(this.snapshotTimer);
+    this.snapshotTimer = setInterval(() => {
+      if (!this.socket.connected) return;
+      void this.buildRegisterPayload({ includeDefinitions: false }).then((payload) => {
+        this.socket.emit("client:snapshot", payload);
+      });
+    }, intervalMs);
+  }
+  /**
+   * Connects to the Cloud runtime.
+   */
+  async connect() {
+    return new Promise((resolve, reject) => {
+      if (this.socket.connected) {
+        resolve();
+        return;
+      }
+      this.connectionAttempted = true;
+      this.hasAuthenticated = false;
+      let resolved = false;
+      let authTimeout;
+      const timeout = setTimeout(() => {
+        if (resolved) return;
+        resolved = true;
+        this.connectionAttempted = false;
+        reject(
+          new ConnectionError(
+            `Connection timeout after 10 seconds. Please check your NEBULAOS_URL (${this.config.url}) and ensure the server is running.`
+          )
+        );
+      }, 1e4);
+      const cleanup = () => {
+        clearTimeout(timeout);
+        if (authTimeout) clearTimeout(authTimeout);
+        this.socket.off("connect", connectHandler);
+        this.socket.off("connect_error", errorHandler);
+        this.socket.off("disconnect", disconnectHandler);
+        this.socket.off("client:online", onlineHandler);
+      };
+      const onlineHandler = () => {
+        if (resolved) return;
+        resolved = true;
+        cleanup();
+        this.connectionAttempted = false;
+        this.hasAuthenticated = true;
+        this.startSnapshotLoop();
+        resolve();
+      };
+      const connectHandler = () => {
+        clearTimeout(timeout);
+        authTimeout = setTimeout(() => {
+          if (resolved) return;
+          resolved = true;
+          cleanup();
+          this.connectionAttempted = false;
+          reject(
+            new AuthenticationError(
+              `Connected but authentication was not confirmed by server. Please check your NEBULAOS_API_KEY environment variable.`
+            )
+          );
+        }, 2500);
+      };
+      const disconnectHandler = (reason) => {
+        if (resolved) return;
+        if (this.connectionAttempted && reason === "io server disconnect") {
+          resolved = true;
+          cleanup();
+          this.connectionAttempted = false;
+          if (this.lastConnectError) {
+            const errorMsg = this.lastConnectError.message.toLowerCase();
+            if (errorMsg.includes("authorization") || errorMsg.includes("token") || errorMsg.includes("unauthorized") || errorMsg.includes("authentication") || errorMsg.includes("api key") || errorMsg.includes("invalid")) {
+              reject(
+                new AuthenticationError(
+                  `Authentication failed: Invalid API key or missing credentials. Please check your NEBULAOS_API_KEY environment variable. (Error: ${this.lastConnectError.message})`
+                )
+              );
+              return;
+            }
+          }
+          reject(
+            new AuthenticationError(
+              `Connection rejected by server: Invalid API key or missing credentials. Please check your NEBULAOS_API_KEY environment variable. (Disconnect reason: ${reason})`
+            )
+          );
+          return;
+        }
+      };
+      const errorHandler = (error) => {
+        if (resolved) return;
+        const errorMsg = error.message.toLowerCase();
+        if (errorMsg.includes("authorization") || errorMsg.includes("token") || errorMsg.includes("unauthorized") || errorMsg.includes("authentication") || errorMsg.includes("api key") || errorMsg.includes("invalid")) {
+          resolved = true;
+          cleanup();
+          this.connectionAttempted = false;
+          reject(
+            new AuthenticationError(
+              `Authentication failed: Invalid API key or missing credentials. Please check your NEBULAOS_API_KEY environment variable. (Server error: ${error.message})`
+            )
+          );
+          return;
+        }
+        if (errorMsg.includes("timeout") || errorMsg.includes("econnrefused")) {
+          resolved = true;
+          cleanup();
+          this.connectionAttempted = false;
+          reject(
+            new ConnectionError(
+              `Connection failed: Unable to reach NebulaOS Cloud at ${this.config.url}. Please check your NEBULAOS_URL environment variable and ensure the server is running. (Error: ${error.message})`
+            )
+          );
+          return;
+        }
+        setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+            cleanup();
+            this.connectionAttempted = false;
+            reject(
+              new ConnectionError(
+                `Connection error: ${error.message}. Please check your NEBULAOS_URL (${this.config.url}) and NEBULAOS_API_KEY.`
+              )
+            );
+          }
+        }, 1e3);
+      };
+      this.socket.once("connect", connectHandler);
+      this.socket.once("connect_error", errorHandler);
+      this.socket.once("disconnect", disconnectHandler);
+      this.socket.once("client:online", onlineHandler);
+      this.socket.connect();
+    });
+  }
+  /**
+   * Disconnects from the server gracefully
+   */
+  async disconnect() {
+    console.log("\u{1F6D1} Disconnecting from NebulaOS Cloud...");
+    if (this.snapshotTimer) clearInterval(this.snapshotTimer);
+    this.snapshotTimer = void 0;
+    if (this.socket.connected) {
+      await this.sendShutdownNotice({ reason: "disconnect()" });
+      this.socket.disconnect();
+    }
+    console.log("\u{1F44B} Disconnected");
+  }
+  /**
+   * Best-effort shutdown notice to allow the Cloud to immediately clean up instance availability.
+   * Never throws: disconnect must be resilient.
+   */
+  async sendShutdownNotice(input) {
+    const payload = {
+      instanceId: this.instanceId,
+      ...input.reason ? { reason: input.reason } : {}
+    };
+    await new Promise((resolve) => {
+      const timeout = setTimeout(() => resolve(), 1500);
+      try {
+        this.socket.emit("client:shutdown", payload, (_response) => {
+          clearTimeout(timeout);
+          resolve();
+        });
+      } catch {
+        clearTimeout(timeout);
+        resolve();
+      }
+    });
+  }
+  /**
+   * Checks if the client is connected
+   */
+  isConnected() {
+    return this.socket.connected;
+  }
+  /**
+   * Returns the client ID
+   */
+  getClientId() {
+    return this.clientId;
+  }
+  getInstanceId() {
+    return this.instanceId;
+  }
+  /**
+   * Returns the socket instance for telemetry
+   */
+  getSocket() {
+    return this.socket;
+  }
+};
+
+// src/client.ts
+import { ConsoleLogger, DomainEvents, Tracing as Tracing3 } from "@nebulaos/core";
+
+// src/telemetry/http-telemetry-exporter.ts
+import axios from "axios";
+var HttpTelemetryExporter = class {
+  constructor(input, config = {}, logger) {
+    this.input = input;
+    this.logger = logger;
+    this.baseUrl = input.cloudUrl.replace(/\/+$/, "");
+    this.timeoutMs = config.timeoutMs ?? 2e3;
+  }
+  baseUrl;
+  timeoutMs;
+  async exportBatch(events) {
+    for (const event of events) {
+      await this.sendSingle(event);
+    }
+  }
+  async sendSingle(event) {
+    const url = `${this.baseUrl}/telemetry/events`;
+    const start = nowMs();
+    try {
+      const res = await axios.post(
+        url,
+        { events: [event] },
+        {
+          timeout: this.timeoutMs,
+          headers: {
+            "Content-Type": "application/json",
+            ...this.input.apiKey ? { Authorization: `Bearer ${this.input.apiKey}` } : {}
+          },
+          // Telemetry should never throw due to non-2xx.
+          validateStatus: () => true
+        }
+      );
+      if (this.logger) {
+        this.logger.debug(
+          "HTTP telemetry sent",
+          {
+            method: "POST",
+            path: "/telemetry/events",
+            status: res.status,
+            durationMs: Number(durationMs(start).toFixed(2)),
+            timeoutMs: this.timeoutMs,
+            event: summarizeTelemetryEvent(event)
+          }
+        );
+      }
+    } catch (err) {
+      if (this.logger) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.logger.warn(
+          "HTTP telemetry failed (best-effort)",
+          {
+            method: "POST",
+            path: "/telemetry/events",
+            durationMs: Number(durationMs(start).toFixed(2)),
+            timeoutMs: this.timeoutMs,
+            error: message,
+            event: summarizeTelemetryEvent(event)
+          }
+        );
+      }
+    }
+  }
+};
+
+// src/domain-events/http-domain-events-exporter.ts
+import axios2 from "axios";
+var HttpDomainEventsExporter = class {
+  constructor(input, config = {}, logger) {
+    this.input = input;
+    this.logger = logger;
+    this.baseUrl = input.cloudUrl.replace(/\/+$/, "");
+    this.timeoutMs = config.timeoutMs ?? 2e3;
+  }
+  baseUrl;
+  timeoutMs;
+  async exportBatch(events) {
+    if (events.length === 0) return;
+    const url = `${this.baseUrl}/execution/events`;
+    const start = nowMs();
+    try {
+      const res = await axios2.post(
+        url,
+        { events },
+        {
+          timeout: this.timeoutMs,
+          headers: {
+            "Content-Type": "application/json",
+            ...this.input.apiKey ? { Authorization: `Bearer ${this.input.apiKey}` } : {}
+          },
+          // Domain events should never throw due to non-2xx.
+          validateStatus: () => true
+        }
+      );
+      if (this.logger) {
+        this.logger.debug(
+          "HTTP domain events sent",
+          {
+            method: "POST",
+            path: "/execution/events",
+            status: res.status,
+            durationMs: Number(durationMs(start).toFixed(2)),
+            timeoutMs: this.timeoutMs,
+            batch: summarizeDomainBatch(events),
+            sample: events.slice(0, 3).map((e) => summarizeDomainEvent(e))
+          }
+        );
+      }
+    } catch {
+      if (this.logger) {
+        this.logger.warn(
+          "HTTP domain events failed (best-effort)",
+          {
+            method: "POST",
+            path: "/execution/events",
+            durationMs: Number(durationMs(start).toFixed(2)),
+            timeoutMs: this.timeoutMs,
+            batch: summarizeDomainBatch(events),
+            sample: events.slice(0, 3).map((e) => summarizeDomainEvent(e))
+          }
+        );
+      }
+    }
+  }
+};
+
+// src/logger/client-debug.ts
+function parseBool(value) {
+  if (!value) return false;
+  const v = value.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+function resolveClientDebugConfig(input) {
+  const env = process.env.NEBULAOS_CLIENT_DEBUG?.trim().toLowerCase();
+  if (env) {
+    if (env === "off" || env === "0" || env === "false") {
+      return { enabled: false, level: "none" };
+    }
+    if (env === "debug") {
+      return { enabled: true, level: "debug" };
+    }
+    if (env === "info") {
+      return { enabled: true, level: "info" };
+    }
+    if (parseBool(env)) {
+      return { enabled: true, level: "debug" };
+    }
+  }
+  if (input?.logLevel) {
+    return {
+      enabled: input.logLevel !== "none",
+      level: input.logLevel
+    };
+  }
+  const enabled = input?.enabled ?? false;
+  const level = input?.level ?? (enabled ? "debug" : "none");
+  return { enabled, level };
+}
+
+// src/client.ts
+import { v4 as uuid2 } from "uuid";
+
+// src/tracing/setup.ts
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { Resource } from "@opentelemetry/resources";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+function setupOTelTracing(config) {
+  const resource = new Resource({
+    "service.name": config.serviceName
+  });
+  const provider = new BasicTracerProvider({ resource });
+  provider.register({
+    contextManager: new AsyncLocalStorageContextManager()
+  });
+  registerInstrumentations({
+    tracerProvider: provider,
+    instrumentations: [
+      new HttpInstrumentation()
+    ]
+  });
+}
+
+// src/tracing/otel-provider.ts
+import { context, trace, SpanStatusCode } from "@opentelemetry/api";
+import {
+  ActiveSpan
+} from "@nebulaos/core";
+var OTelTracingProvider = class {
+  constructor(serviceName, exporter) {
+    this.exporter = exporter;
+    this.tracer = trace.getTracer(serviceName);
+  }
+  tracer;
+  /**
+   * 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)
+   */
+  ensureW3cHex(id, hexLen) {
+    if (!id) return void 0;
+    const hexRegex = hexLen === 16 ? /^[0-9a-f]{16}$/ : /^[0-9a-f]{32}$/;
+    if (hexRegex.test(id)) return id;
+    try {
+      const hex = Buffer.from(id, "base64").toString("hex");
+      return hex.slice(0, hexLen).padStart(hexLen, "0");
+    } catch {
+      return void 0;
+    }
+  }
+  startSpan(input) {
+    const parentCtx = context.active();
+    const parentSpan = trace.getSpan(parentCtx);
+    const otelSpan = this.tracer.startSpan(
+      `${input.kind}:${input.name}`,
+      {
+        attributes: {
+          "nebula.span.kind": input.kind,
+          "nebula.span.name": input.name,
+          ...input.correlationId ? { "nebula.correlationId": input.correlationId } : {},
+          ...input.executionId ? { "nebula.executionId": input.executionId } : {}
+        }
+      },
+      parentCtx
+    );
+    const spanContext = otelSpan.spanContext();
+    const traceId = this.ensureW3cHex(spanContext.traceId, 32) ?? spanContext.traceId;
+    const spanId = this.ensureW3cHex(spanContext.spanId, 16) ?? spanContext.spanId;
+    const parentSpanId = this.ensureW3cHex(parentSpan?.spanContext().spanId, 16);
+    const activeSpan = new OTelActiveSpan(
+      traceId,
+      spanId,
+      parentSpanId,
+      input.kind,
+      input.name,
+      input.correlationId,
+      input.executionId,
+      this.exporter,
+      otelSpan
+    );
+    const startEvent = {
+      v: 1,
+      type: "telemetry:span:start",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      trace: { traceId, spanId, parentSpanId },
+      correlationId: input.correlationId,
+      executionId: input.executionId,
+      span: {
+        kind: input.kind,
+        name: input.name,
+        data: input.data ?? {}
+      }
+    };
+    this.exporter.exportBatch([startEvent]).catch(() => {
+    });
+    return activeSpan;
+  }
+  getContext() {
+    const span = trace.getSpan(context.active());
+    if (!span) return void 0;
+    const sc = span.spanContext();
+    return {
+      traceId: this.ensureW3cHex(sc.traceId, 32) ?? sc.traceId,
+      spanId: this.ensureW3cHex(sc.spanId, 16) ?? sc.spanId
+    };
+  }
+  async withSpan(input, fn) {
+    const parentCtx = context.active();
+    const parentSpan = trace.getSpan(parentCtx);
+    const otelSpan = this.tracer.startSpan(
+      `${input.kind}:${input.name}`,
+      {
+        attributes: {
+          "nebula.span.kind": input.kind,
+          "nebula.span.name": input.name,
+          ...input.correlationId ? { "nebula.correlationId": input.correlationId } : {},
+          ...input.executionId ? { "nebula.executionId": input.executionId } : {}
+        }
+      },
+      parentCtx
+    );
+    const spanContext = otelSpan.spanContext();
+    const traceId = this.ensureW3cHex(spanContext.traceId, 32) ?? spanContext.traceId;
+    const spanId = this.ensureW3cHex(spanContext.spanId, 16) ?? spanContext.spanId;
+    const parentSpanId = this.ensureW3cHex(parentSpan?.spanContext().spanId, 16);
+    const activeSpan = new OTelActiveSpan(
+      traceId,
+      spanId,
+      parentSpanId,
+      input.kind,
+      input.name,
+      input.correlationId,
+      input.executionId,
+      this.exporter,
+      otelSpan
+    );
+    const startEvent = {
+      v: 1,
+      type: "telemetry:span:start",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      trace: {
+        traceId,
+        spanId,
+        parentSpanId
+      },
+      correlationId: input.correlationId,
+      executionId: input.executionId,
+      span: {
+        kind: input.kind,
+        name: input.name,
+        data: input.data ?? {}
+      }
+    };
+    try {
+      await this.exporter.exportBatch([startEvent]);
+    } catch {
+    }
+    const ctx = trace.setSpan(parentCtx, otelSpan);
+    return context.with(ctx, async () => {
+      try {
+        const result = await fn(activeSpan);
+        if (!activeSpan.isEnded) {
+          await activeSpan.end({ status: "success" });
+        }
+        return result;
+      } catch (error) {
+        await activeSpan.end({ status: "error" });
+        throw error;
+      }
+    });
+  }
+};
+var OTelActiveSpan = class extends ActiveSpan {
+  constructor(traceId, spanId, parentSpanId, kind, name, correlationId, executionId, exporter, otelSpan) {
+    super(traceId, spanId, parentSpanId, kind, name, correlationId, executionId, exporter);
+    this.otelSpan = otelSpan;
+  }
+  async end(input) {
+    if (this.isEnded) return;
+    if (input.status === "error") {
+      this.otelSpan.setStatus({ code: SpanStatusCode.ERROR });
+    } else {
+      this.otelSpan.setStatus({ code: SpanStatusCode.OK });
+    }
+    this.otelSpan.end();
+    await super.end(input);
+  }
+};
+
+// src/http/instrumented-http-client.ts
+import { Tracing as Tracing2 } from "@nebulaos/core";
+var InstrumentedHttpClient = class {
+  async fetch(url, options) {
+    const method = options?.method || "GET";
+    const spanName = `http:${method} ${new URL(url).origin}`;
+    return Tracing2.withSpan(
+      {
+        kind: "http",
+        name: spanName,
+        data: {
+          "http.method": method,
+          "http.url": url
+        }
+      },
+      async (span) => {
+        const startTime = Date.now();
+        try {
+          const response = await fetch(url, options);
+          const contentType = response.headers.get("content-type") || "";
+          let data;
+          if (contentType.includes("application/json")) {
+            data = await response.json();
+          } else {
+            data = await response.text();
+          }
+          await span.end({
+            status: response.ok ? "success" : "error",
+            data: {
+              "http.status_code": response.status,
+              "http.response_content_length": response.headers.get("content-length"),
+              "http.duration_ms": Date.now() - startTime
+            }
+          });
+          return {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            data
+          };
+        } catch (error) {
+          await span.end({
+            status: "error",
+            data: {
+              "http.error": error instanceof Error ? error.message : String(error),
+              "http.duration_ms": Date.now() - startTime
+            }
+          });
+          throw error;
+        }
+      }
+    );
+  }
+  async get(url, options) {
+    return this.fetch(url, { ...options, method: "GET" });
+  }
+  async post(url, body, options) {
+    return this.fetch(url, {
+      ...options,
+      method: "POST",
+      body: body ? JSON.stringify(body) : void 0,
+      headers: { "Content-Type": "application/json", ...options?.headers }
+    });
+  }
+};
+
+// src/client.ts
+var NebulaClient = class {
+  constructor(config) {
+    this.config = config;
+    clientConfigSchema.parse(config);
+    if (!config.clientId) {
+      config.clientId = `client-${uuid2()}`;
+    }
+    if (config.server) {
+      this.setGlobalClientContext(config.server.apiKey, config.server.url);
+    }
+    this.registry = new Registry();
+    this.registry.setHttpClient(new InstrumentedHttpClient());
+    config.agents?.forEach((agent) => this.registry.registerAgent(agent));
+    config.tools?.forEach((tool) => this.registry.registerTool(tool));
+    config.workflows?.forEach((workflow) => this.registry.registerWorkflow(workflow));
+    if (config.server) {
+      const debug = resolveClientDebugConfig({
+        logLevel: config.logLevel,
+        // deprecated:
+        enabled: config.debug?.enabled,
+        level: config.debug?.level
+      });
+      if (debug.enabled) {
+        this.logger = new ConsoleLogger(debug.level, "nebulaos/client");
+        this.logger.info(
+          "Client debug enabled",
+          { level: debug.level, ws: true, http: true }
+        );
+      }
+      this.serverConnection = new ServerConnection({
+        url: config.server.url,
+        apiKey: config.server.apiKey,
+        clientId: config.clientId
+      }, this.logger);
+      this.serverConnection.setRegistry(this.registry);
+      this.telemetryExporter = new HttpTelemetryExporter(
+        {
+          cloudUrl: config.server.url,
+          apiKey: config.server.apiKey,
+          clientId: config.clientId
+        },
+        {
+          timeoutMs: 2e3
+        },
+        this.logger
+      );
+      Tracing3.setExporter(this.telemetryExporter);
+      setupOTelTracing({
+        serviceName: config.clientId ?? "nebulaos-client"
+      });
+      const otelProvider = new OTelTracingProvider(
+        config.clientId ?? "nebulaos-client",
+        this.telemetryExporter
+      );
+      Tracing3.setProvider(otelProvider);
+      this.domainEventsExporter = new HttpDomainEventsExporter(
+        {
+          cloudUrl: config.server.url,
+          apiKey: config.server.apiKey,
+          clientId: config.clientId
+        },
+        {
+          timeoutMs: 2e3
+        },
+        this.logger
+      );
+      DomainEvents.setExporter(this.domainEventsExporter);
+    }
+  }
+  registry;
+  serverConnection;
+  telemetryExporter;
+  domainEventsExporter;
+  logger;
+  registerAgent(agent) {
+    this.registry.registerAgent(agent);
+  }
+  registerTool(tool) {
+    this.registry.registerTool(tool);
+  }
+  registerWorkflow(workflow) {
+    this.registry.registerWorkflow(workflow);
+  }
+  async start() {
+    if (this.serverConnection) {
+      this.serverConnection.registerResources(
+        this.registry.listAgents(),
+        this.registry.listTools(),
+        this.registry.listWorkflows()
+      );
+      try {
+        await this.serverConnection.connect();
+      } catch (error) {
+        if (error instanceof Error) {
+          throw error;
+        }
+        throw new Error(`Failed to connect to NebulaOS Cloud: ${String(error)}`);
+      }
+    }
+  }
+  async stop() {
+    await this.serverConnection?.disconnect();
+  }
+  getClientId() {
+    return this.serverConnection?.getClientId();
+  }
+  isConnected() {
+    return this.serverConnection?.isConnected() ?? false;
+  }
+  /**
+   * 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
+   */
+  setGlobalClientContext(apiKey, serverUrl) {
+    try {
+      import("@nebulaos/rag-openai-skill").then((module) => {
+        if (module.ClientContext) {
+          module.ClientContext.setApiKey(apiKey);
+          module.ClientContext.setServerUrl(serverUrl);
+        }
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+};
+
+// src/telemetry/telemetry.service.ts
+var TelemetryService = class {
+};
+
+// src/telemetry/batcher.ts
+var Batcher = class {
+};
+
+// src/telemetry/socket-telemetry-exporter.ts
+var SocketTelemetryExporter = class {
+  constructor(serverConnection, config = {}) {
+    this.serverConnection = serverConnection;
+    this.config = config;
+  }
+  queue = [];
+  flushTimer;
+  flushing = false;
+  async exportBatch(events) {
+    this.queue.push(...events);
+    this.ensureTimer();
+    await this.flushIfNeeded();
+  }
+  async flush() {
+    if (this.flushing) return;
+    if (this.queue.length === 0) return;
+    this.flushing = true;
+    try {
+      const maxBatchSize = this.config.maxBatchSize ?? 50;
+      while (this.queue.length > 0) {
+        const batch = this.queue.splice(0, maxBatchSize);
+        await this.sendTelemetryBatch(batch);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+  stop() {
+    if (this.flushTimer) clearInterval(this.flushTimer);
+    this.flushTimer = void 0;
+  }
+  async sendTelemetryBatch(events) {
+    if (!this.serverConnection.isConnected()) {
+      return;
+    }
+    const socket = this.serverConnection.getSocket();
+    socket.emit("telemetry:batch", {
+      clientId: this.serverConnection.getClientId(),
+      events
+    });
+  }
+  ensureTimer() {
+    if (this.flushTimer) return;
+    const flushIntervalMs = this.config.flushIntervalMs ?? 500;
+    this.flushTimer = setInterval(() => {
+      void this.flush();
+    }, flushIntervalMs);
+  }
+  async flushIfNeeded() {
+    const maxBatchSize = this.config.maxBatchSize ?? 50;
+    if (this.queue.length >= maxBatchSize) {
+      await this.flush();
+    }
+  }
+};
+
+// src/memory/db-memory.ts
+var DBMemory = class {
+  async get(_key, _sessionId) {
+    return null;
+  }
+  async set(_key, _value, _sessionId, _ttl) {
+  }
+  async delete(_key, _sessionId) {
+  }
+  async clear(_sessionId) {
+  }
+  async getHistory(_sessionId, _limit) {
+    return [];
+  }
+};
+
+// src/prompts/prompt-capture.ts
+var PromptCapture = class {
+};
+
+// src/rag/rag-client.ts
+var RAGClient = class {
+};
+export {
+  AuthenticationError,
+  Batcher,
+  ClientError,
+  ConnectionError,
+  DBMemory,
+  HttpDomainEventsExporter,
+  HttpTelemetryExporter,
+  InstrumentedHttpClient,
+  NebulaClient,
+  NotFoundError,
+  OTelTracingProvider,
+  PromptCapture,
+  RAGClient,
+  RegistryError,
+  SocketTelemetryExporter,
+  TelemetryService,
+  clientConfigSchema,
+  otelTracingConfigSchema,
+  serverConfigSchema,
+  setupOTelTracing
+};
+//# sourceMappingURL=index.mjs.map