@nebulaos/core 0.1.1 → 0.2.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, iamkun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,206 +1,206 @@
-# @starya/nebulaos-core
-
-The core of NebulaOS for building AI Agents and complex Workflows. This package provides the essential primitives for orchestration, state management, and model abstraction.
-
-## Installation
-
-```bash
-pnpm add @starya/nebulaos-core
-```
-
----
-
-## ✨ Features Overview
-
-### 🤖 Agent System
-- ✅ **Multi-Step Reasoning** - Automatic tool calling loops with configurable max steps
-- ✅ **Streaming Support** - Real-time token streaming with `executeStream()`
-- ✅ **Tool Calling** - Function calling with Zod schema validation
-- ✅ **Parallel Tool Execution** - Execute multiple tools simultaneously
-- ✅ **Structured Outputs** - JSON mode with schema validation
-- ✅ **Memory Management** - Pluggable memory implementations (InMemory, Redis, etc.)
-- ✅ **Dynamic Instructions** - Support for async instruction resolution
-- ✅ **Request/Response Interceptors** - Middleware for RAG, sanitization, etc.
-- ✅ **Multimodal Support** - Text + Images (via ContentPart[])
-
-### 🔄 Workflow Orchestration
-- ✅ **Fluent API** - Declarative workflow definition (`.start().step().finish()`)
-- ✅ **Branching & Parallel** - Conditional paths and concurrent execution
-- ✅ **State Persistence** - Save/resume workflow state (requires state store)
-- ✅ **Retry Policies** - Exponential/Linear backoff with configurable attempts
-- ✅ **Input/Output Validation** - Zod schema validation at boundaries
-- ✅ **Queue Integration** - Async workflow execution (requires queue adapter)
-- ✅ **Event-Driven** - Lifecycle events for monitoring and logging
-
-### 📊 Observability & Tracing
-- ✅ **Distributed Tracing** - Automatic trace/span propagation via AsyncLocalStorage
-- ✅ **Event System** - Rich lifecycle events (`execution:start`, `llm:call`, `tool:result`, etc.)
-- ✅ **Correlation IDs** - Track requests across nested operations
-- ✅ **Structured Logging** - Beautiful console logs with ANSI colors and metadata trees
-- ✅ **Log Levels** - Configurable (debug, info, warn, error)
-- ✅ **Custom Loggers** - Implement `ILogger` for Datadog, CloudWatch, etc.
-- ✅ **PII Masking** - GDPR/LGPD compliance with pluggable masking
-
-### 🧪 Testing & Quality
-- ✅ **Provider Compliance Suite** - Reusable test suite for model providers
-- ✅ **Mock Implementations** - MockProvider, MockStateStore for unit tests
-- ✅ **Integration Tests** - Live API tests with real providers
-- ✅ **Type Safety** - Full TypeScript support with strict typing
-- ✅ **Test Coverage** - Comprehensive unit and integration tests
-
-### 🔌 Provider System
-- ✅ **Provider Abstraction** - IModel interface for any LLM (OpenAI, Anthropic, etc.)
-- ✅ **Token Usage Tracking** - Automatic accumulation across multi-step flows
-- ✅ **Streaming Protocol** - Unified chunk types (content_delta, tool_call_start, etc.)
-- ✅ **Error Handling** - Graceful degradation and retry logic
-
----
-
-## 🆕 Recent Updates
-
-### v0.0.1 - Distributed Tracing & Stream Parity
-- **Distributed Tracing**: Automatic trace/span propagation across Agent → Workflow → Tool chains
-- **executeStream() Parity**: Full feature parity with execute() including token tracking, events, and max steps fallback
-- **Enhanced Logging**: Color-coded terminal output with hierarchical metadata display
-- **Response Interceptors**: Now run only on final responses (not intermediate tool calls)
-- **Test Coverage**: Expanded to 22 unit tests + 7 integration tests
-
----
-
-## Core Components
-
-### 1. Agent (`Agent`)
-
-The main class that manages the lifecycle of AI interaction.
-
-### Key Features
-*   **Memory-First**: Every agent requires a memory implementation (e.g., `InMemory`) to maintain context.
-*   **Interceptors**: Middleware to modify requests and responses.
-    *   **Request Interceptors**: Run before each LLM call. Useful for context injection (RAG).
-    *   **Response Interceptors**: Run **only on the final response** (or when there are no tool calls), ideal for output sanitization and formatting.
-*   **Streaming**: Native support for text and tool call streaming.
-*   **Observability**: Integrated event-based logging system with PII Masking support (GDPR/LGPD).
-
-### Complete Example
-
-```typescript
-import { Agent, InMemory, Tool, z } from "@starya/nebulaos-core";
-import { OpenAI } from "@starya/nebulaos-openai";
-
-// 1. Tools
-const calculator = new Tool({
-  id: "calculator",
-  description: "Adds two numbers",
-  inputSchema: z.object({ a: z.number(), b: z.number() }),
-  handler: async (ctx, input) => ({ result: input.a + input.b })
-});
-
-// 2. Agent
-const agent = new Agent({
-  name: "financial-assistant",
-  model: new OpenAI({
-    apiKey: process.env.OPENAI_API_KEY!,
-    model: "gpt-4o"
-  }),
-  memory: new InMemory(),
-  instructions: "You help with financial calculations.",
-  tools: [calculator],
-  logLevel: "info", // Detailed console logs
-  interceptors: {
-    response: [
-        async (res) => {
-            // Format final output to uppercase (example)
-            if (res.content) res.content = res.content.toUpperCase();
-            return res;
-        }
-    ]
-  }
-});
-
-// 3. Execution
-await agent.addMessage({ role: "user", content: "How much is 10 + 20?" });
-const result = await agent.execute();
-console.log(result.content);
-```
-
----
-
-## 🔄 Workflow (`Workflow`)
-
-Orchestrator for long-running and complex processes, supporting persistence, retries, and validation.
-
-### Features
-*   **Fluent API**: Declarative definition (`.start().step().branch().finish()`).
-*   **State Persistence**: Saves the state of each step (requires `stateStore`).
-*   **Resilience**: Configurable Retry Policies (Exponential, Linear).
-*   **Type-Safe**: Input and output validation with Zod.
-
-### Workflow Example
-
-```typescript
-import { Workflow, MockStateStore } from "@starya/nebulaos-core";
-import { z } from "zod";
-
-const workflow = new Workflow({
-  id: "order-processing",
-  stateStore: new MockStateStore(), // Or real implementation (Redis/Postgres)
-  retryPolicy: {
-      maxAttempts: 3,
-      backoff: "exponential",
-      initialDelay: 1000
-  }
-})
-.start(async ({ input }) => {
-    console.log("Validating order", input);
-    return input;
-})
-.step("payment", async ({ input }) => {
-    // Payment logic
-    return { status: "paid", id: input.id };
-})
-.finish(async ({ input }) => {
-    return { message: `Order ${input.id} processed successfully` };
-});
-
-// Execution
-const result = await workflow.run({ id: 123, total: 500 });
-```
-
----
-
-## 🛡️ Logging & Observability
-
-The Core emits rich events during execution (`execution:start`, `llm:call`, `tool:result`).
-
-### Configuration
-The default logger (`ConsoleLogger`) can be configured via `logLevel`. For production, you can implement the `ILogger` interface to send logs to Datadog, CloudWatch, etc.
-
-### PII Masking (Privacy)
-Protect sensitive data in logs by configuring a `piiMasker`.
-
-```typescript
-const agent = new Agent({
-  // ...
-  piiMasker: {
-      mask: (text) => text.replace(/\d{3}\.\d{3}\.\d{3}-\d{2}/g, "***") // Example mask
-  }
-});
-```
-
----
-
-## 🧪 Testing & Compliance
-
-### Package Tests
-```bash
-pnpm test
-```
-
-### Provider Compliance Suite
-If you are creating a new Provider (e.g., Anthropic), use the compliance suite to ensure full compatibility.
-
-```typescript
-import { runProviderComplianceTests } from "@starya/nebulaos-core/test-utils";
-
-runProviderComplianceTests(() => new MyNewProvider(...), { runLiveTests: true });
-```
+# @starya/nebulaos-core
+
+The core of NebulaOS for building AI Agents and complex Workflows. This package provides the essential primitives for orchestration, state management, and model abstraction.
+
+## Installation
+
+```bash
+pnpm add @starya/nebulaos-core
+```
+
+---
+
+## ✨ Features Overview
+
+### 🤖 Agent System
+- ✅ **Multi-Step Reasoning** - Automatic tool calling loops with configurable max steps
+- ✅ **Streaming Support** - Real-time token streaming with `executeStream()`
+- ✅ **Tool Calling** - Function calling with Zod schema validation
+- ✅ **Parallel Tool Execution** - Execute multiple tools simultaneously
+- ✅ **Structured Outputs** - JSON mode with schema validation
+- ✅ **Memory Management** - Pluggable memory implementations (InMemory, Redis, etc.)
+- ✅ **Dynamic Instructions** - Support for async instruction resolution
+- ✅ **Request/Response Interceptors** - Middleware for RAG, sanitization, etc.
+- ✅ **Multimodal Support** - Text + Images (via ContentPart[])
+
+### 🔄 Workflow Orchestration
+- ✅ **Fluent API** - Declarative workflow definition (`.start().step().finish()`)
+- ✅ **Branching & Parallel** - Conditional paths and concurrent execution
+- ✅ **State Persistence** - Save/resume workflow state (requires state store)
+- ✅ **Retry Policies** - Exponential/Linear backoff with configurable attempts
+- ✅ **Input/Output Validation** - Zod schema validation at boundaries
+- ✅ **Queue Integration** - Async workflow execution (requires queue adapter)
+- ✅ **Event-Driven** - Lifecycle events for monitoring and logging
+
+### 📊 Observability & Tracing
+- ✅ **Distributed Tracing** - Automatic trace/span propagation via AsyncLocalStorage
+- ✅ **Event System** - Rich lifecycle events (`execution:start`, `llm:call`, `tool:result`, etc.)
+- ✅ **Correlation IDs** - Track requests across nested operations
+- ✅ **Structured Logging** - Beautiful console logs with ANSI colors and metadata trees
+- ✅ **Log Levels** - Configurable (debug, info, warn, error)
+- ✅ **Custom Loggers** - Implement `ILogger` for Datadog, CloudWatch, etc.
+- ✅ **PII Masking** - GDPR/LGPD compliance with pluggable masking
+
+### 🧪 Testing & Quality
+- ✅ **Provider Compliance Suite** - Reusable test suite for model providers
+- ✅ **Mock Implementations** - MockProvider, MockStateStore for unit tests
+- ✅ **Integration Tests** - Live API tests with real providers
+- ✅ **Type Safety** - Full TypeScript support with strict typing
+- ✅ **Test Coverage** - Comprehensive unit and integration tests
+
+### 🔌 Provider System
+- ✅ **Provider Abstraction** - IModel interface for any LLM (OpenAI, Anthropic, etc.)
+- ✅ **Token Usage Tracking** - Automatic accumulation across multi-step flows
+- ✅ **Streaming Protocol** - Unified chunk types (content_delta, tool_call_start, etc.)
+- ✅ **Error Handling** - Graceful degradation and retry logic
+
+---
+
+## 🆕 Recent Updates
+
+### v0.0.1 - Distributed Tracing & Stream Parity
+- **Distributed Tracing**: Automatic trace/span propagation across Agent → Workflow → Tool chains
+- **executeStream() Parity**: Full feature parity with execute() including token tracking, events, and max steps fallback
+- **Enhanced Logging**: Color-coded terminal output with hierarchical metadata display
+- **Response Interceptors**: Now run only on final responses (not intermediate tool calls)
+- **Test Coverage**: Expanded to 22 unit tests + 7 integration tests
+
+---
+
+## Core Components
+
+### 1. Agent (`Agent`)
+
+The main class that manages the lifecycle of AI interaction.
+
+### Key Features
+*   **Memory-First**: Every agent requires a memory implementation (e.g., `InMemory`) to maintain context.
+*   **Interceptors**: Middleware to modify requests and responses.
+    *   **Request Interceptors**: Run before each LLM call. Useful for context injection (RAG).
+    *   **Response Interceptors**: Run **only on the final response** (or when there are no tool calls), ideal for output sanitization and formatting.
+*   **Streaming**: Native support for text and tool call streaming.
+*   **Observability**: Integrated event-based logging system with PII Masking support (GDPR/LGPD).
+
+### Complete Example
+
+```typescript
+import { Agent, InMemory, Tool, z } from "@starya/nebulaos-core";
+import { OpenAI } from "@starya/nebulaos-openai";
+
+// 1. Tools
+const calculator = new Tool({
+  id: "calculator",
+  description: "Adds two numbers",
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  handler: async (ctx, input) => ({ result: input.a + input.b })
+});
+
+// 2. Agent
+const agent = new Agent({
+  name: "financial-assistant",
+  model: new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-4o"
+  }),
+  memory: new InMemory(),
+  instructions: "You help with financial calculations.",
+  tools: [calculator],
+  logLevel: "info", // Detailed console logs
+  interceptors: {
+    response: [
+        async (res) => {
+            // Format final output to uppercase (example)
+            if (res.content) res.content = res.content.toUpperCase();
+            return res;
+        }
+    ]
+  }
+});
+
+// 3. Execution
+await agent.addMessage({ role: "user", content: "How much is 10 + 20?" });
+const result = await agent.execute();
+console.log(result.content);
+```
+
+---
+
+## 🔄 Workflow (`Workflow`)
+
+Orchestrator for long-running and complex processes, supporting persistence, retries, and validation.
+
+### Features
+*   **Fluent API**: Declarative definition (`.start().step().branch().finish()`).
+*   **State Persistence**: Saves the state of each step (requires `stateStore`).
+*   **Resilience**: Configurable Retry Policies (Exponential, Linear).
+*   **Type-Safe**: Input and output validation with Zod.
+
+### Workflow Example
+
+```typescript
+import { Workflow, MockStateStore } from "@starya/nebulaos-core";
+import { z } from "zod";
+
+const workflow = new Workflow({
+  id: "order-processing",
+  stateStore: new MockStateStore(), // Or real implementation (Redis/Postgres)
+  retryPolicy: {
+      maxAttempts: 3,
+      backoff: "exponential",
+      initialDelay: 1000
+  }
+})
+.start(async ({ input }) => {
+    console.log("Validating order", input);
+    return input;
+})
+.step("payment", async ({ input }) => {
+    // Payment logic
+    return { status: "paid", id: input.id };
+})
+.finish(async ({ input }) => {
+    return { message: `Order ${input.id} processed successfully` };
+});
+
+// Execution
+const result = await workflow.run({ id: 123, total: 500 });
+```
+
+---
+
+## 🛡️ Logging & Observability
+
+The Core emits rich events during execution (`execution:start`, `llm:call`, `tool:result`).
+
+### Configuration
+The default logger (`ConsoleLogger`) can be configured via `logLevel`. For production, you can implement the `ILogger` interface to send logs to Datadog, CloudWatch, etc.
+
+### PII Masking (Privacy)
+Protect sensitive data in logs by configuring a `piiMasker`.
+
+```typescript
+const agent = new Agent({
+  // ...
+  piiMasker: {
+      mask: (text) => text.replace(/\d{3}\.\d{3}\.\d{3}-\d{2}/g, "***") // Example mask
+  }
+});
+```
+
+---
+
+## 🧪 Testing & Compliance
+
+### Package Tests
+```bash
+pnpm test
+```
+
+### Provider Compliance Suite
+If you are creating a new Provider (e.g., Anthropic), use the compliance suite to ensure full compatibility.
+
+```typescript
+import { runProviderComplianceTests } from "@starya/nebulaos-core/test-utils";
+
+runProviderComplianceTests(() => new MyNewProvider(...), { runLiveTests: true });
+```

package/dist/agent/Agent.d.ts

@@ -74,6 +74,11 @@ export declare class Agent extends BaseAgent {
      * This is typically called by the client package with InstrumentedHttpClient.
      */
     setHttpClient(client: IHttpClient): void;
+    /**
+     * Sets the client reference on the memory and skills.
+     * Called by NebulaClient after connecting, so memory/skills can access client config.
+     */
+    setClient(client: unknown): void;
     private initializeSkills;
     private resolveInstructions;
     private isInstruction;

package/dist/agent/Agent.js

@@ -40,6 +40,24 @@ class Agent extends BaseAgent_js_1.BaseAgent {
     setHttpClient(client) {
         this.httpClient = client;
     }
+    /**
+     * Sets the client reference on the memory and skills.
+     * Called by NebulaClient after connecting, so memory/skills can access client config.
+     */
+    setClient(client) {
+        // Propagate to memory
+        const memory = this.config.memory;
+        if (memory && typeof memory.setClient === 'function') {
+            memory.setClient(client);
+        }
+        // Propagate to skills
+        const skills = this.config.skills || [];
+        for (const skill of skills) {
+            if (typeof skill.setClient === 'function') {
+                skill.setClient(client);
+            }
+        }
+    }
     // ==========================================================================
     // Skills Initialization
     // ==========================================================================

package/dist/agent/instruction/index.d.ts

@@ -15,6 +15,11 @@ export declare class Instruction implements IInstruction {
      * Suporta caminhos absolutos ou relativos ao CWD.
      */
     static fromFile(filePath: string, variables?: InstructionVariables): Promise<Instruction>;
+    /**
+     * Cria uma instrução a partir de um arquivo de texto de forma síncrona.
+     * Suporta caminhos absolutos ou relativos ao CWD.
+     */
+    static fromFileSync(filePath: string, variables?: InstructionVariables): Instruction;
     /**
      * Cria uma instrução a partir de uma string direta.
      */

package/dist/agent/instruction/index.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Instruction = void 0;
 const fs = __importStar(require("fs/promises"));
+const fsSync = __importStar(require("fs"));
 class Instruction {
     content;
     variables = {};
@@ -66,6 +67,19 @@ class Instruction {
             throw new Error(`Failed to load instruction from file: ${filePath}. Error: ${error}`);
         }
     }
+    /**
+     * Cria uma instrução a partir de um arquivo de texto de forma síncrona.
+     * Suporta caminhos absolutos ou relativos ao CWD.
+     */
+    static fromFileSync(filePath, variables = {}) {
+        try {
+            const content = fsSync.readFileSync(filePath, "utf-8");
+            return new Instruction(content, variables);
+        }
+        catch (error) {
+            throw new Error(`Failed to load instruction from file: ${filePath}. Error: ${error}`);
+        }
+    }
     /**
      * Cria uma instrução a partir de uma string direta.
      */

package/dist/agent/skills/index.d.ts

@@ -54,6 +54,14 @@ export interface ISkill {
      * @returns Additional instructions text for the agent
      */
     getInstructions?(): string | Promise<string>;
+    /**
+     * Optional method to receive the client reference.
+     * Called by the Agent when it receives setClient() from the NebulaClient.
+     * Skills can extract configuration (apiKey, serverUrl, etc.) from the client.
+     *
+     * @param client - The NebulaClient instance (typed as unknown to avoid circular dependency)
+     */
+    setClient?(client: unknown): void;
 }
 /**
  * Helper function to validate that an object implements ISkill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulaos/core",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Core primitives for NebulaOS (Agent, Workflow, Providers)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,13 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:e2e:providers": "jest packages/core/__tests__/integration/providers.e2e.spec.ts --runInBand --testTimeout=60000",
+    "prepublishOnly": "pnpm build"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/Psyco-AI-Tech/starya-nebulaos.git",
@@ -30,27 +37,21 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@nebulaos/types": "workspace:*",
     "uuid": "^9.0.1",
     "zod": "^3.0.0",
-    "zod-to-json-schema": "^3.0.0",
-    "@nebulaos/types": "0.1.0"
+    "zod-to-json-schema": "^3.0.0"
   },
   "devDependencies": {
+    "@nebulaos/oci": "workspace:*",
+    "@nebulaos/openai": "workspace:*",
+    "@nebulaos/google-gemini": "workspace:*",
     "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
     "@types/uuid": "^9.0.8",
     "dotenv": "^17.2.3",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
-    "typescript": "^5.0.0",
-    "@nebulaos/google-gemini": "0.0.1",
-    "@nebulaos/oci": "0.0.1",
-    "@nebulaos/openai": "0.0.1"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:e2e:providers": "jest packages/core/__tests__/integration/providers.e2e.spec.ts --runInBand --testTimeout=60000"
+    "typescript": "^5.0.0"
   }
-}
+}