@nebulaos/core 0.1.1

package/dist/agent/BaseAgent.d.ts

@@ -0,0 +1,53 @@
+import { AgentResult } from "./Agent.js";
+import type { AgentEventMap, AgentEventName } from "./events/events.js";
+import { IPIIMasker } from "../lgpd/index.js";
+import type { IMemory } from "./memory/index.js";
+import type { Message } from "./provider/index.js";
+import type { AgentExecuteOptions } from "./Agent.js";
+export type AgentKind = 'agent' | 'team:router' | 'team:handoff' | 'team:hierarchical' | 'team:pipeline' | 'team:committee' | 'team';
+export declare abstract class BaseAgent {
+    /**
+     * Developer-defined, stable, semantic identifier.
+     * This must not change across renames to preserve runtime registry identity.
+     */
+    readonly id: string;
+    readonly name: string;
+    /**
+     * Identifies the type of agent (agent, router-team, handoff-team, etc.)
+     * Useful for UI/registry differentiation.
+     */
+    readonly kind: AgentKind;
+    private emitter;
+    protected piiMasker?: IPIIMasker;
+    protected memory?: IMemory;
+    constructor(id: string, name: string, piiMasker?: IPIIMasker, memory?: IMemory);
+    /**
+     * Executes the agent. All agent-like implementations (including multi-agent teams)
+     * must accept an optional input string and optional execution options.
+     */
+    abstract execute(input?: string, options?: AgentExecuteOptions): Promise<AgentResult>;
+    /**
+     * Adds a message to this agent's memory (if configured).
+     * Multi-agent teams MUST provide a memory implementation if they expect to be used
+     * through standardized execution surfaces (e.g., HTTP gateways).
+     */
+    addMessage(message: Message): Promise<void>;
+    /**
+     * Emits a typed event with automatic context injection (trace, timestamp).
+     *
+     * @param event The event name (e.g., 'agent:execution:start')
+     * @param payload The event payload containing 'data' and optional context like 'correlationId'
+     */
+    protected emit<K extends AgentEventName>(event: K, payload: {
+        data: AgentEventMap[K]["data"];
+        correlationId?: string;
+        executionId?: string;
+    }): boolean;
+    on<K extends AgentEventName>(event: K, listener: (data: AgentEventMap[K]) => void): this;
+    once<K extends AgentEventName>(event: K, listener: (data: AgentEventMap[K]) => void): this;
+    off<K extends AgentEventName>(event: K, listener: (data: AgentEventMap[K]) => void): this;
+    /**
+     * Recursively masks PII in the event payload
+     */
+    private maskEventData;
+}

package/dist/agent/BaseAgent.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAgent = void 0;
+const events_1 = require("events");
+const index_js_1 = require("../tracing/index.js");
+const index_js_2 = require("../execution-context/index.js");
+const index_js_3 = require("../domain-events/index.js");
+class BaseAgent {
+    /**
+     * Developer-defined, stable, semantic identifier.
+     * This must not change across renames to preserve runtime registry identity.
+     */
+    id;
+    name;
+    /**
+     * Identifies the type of agent (agent, router-team, handoff-team, etc.)
+     * Useful for UI/registry differentiation.
+     */
+    kind = 'agent';
+    emitter = new events_1.EventEmitter();
+    piiMasker;
+    memory;
+    constructor(id, name, piiMasker, memory) {
+        if (!id || !id.trim()) {
+            throw new Error("Agent id is required");
+        }
+        if (!name || !name.trim()) {
+            throw new Error("Agent name is required");
+        }
+        this.id = id.trim();
+        this.name = name.trim();
+        this.piiMasker = piiMasker;
+        this.memory = memory;
+    }
+    /**
+     * Adds a message to this agent's memory (if configured).
+     * Multi-agent teams MUST provide a memory implementation if they expect to be used
+     * through standardized execution surfaces (e.g., HTTP gateways).
+     */
+    async addMessage(message) {
+        if (!this.memory) {
+            throw new Error(`Agent '${this.name}' does not have memory configured`);
+        }
+        await this.memory.addMessage(message);
+    }
+    // ==========================================================================
+    // Typed Event Emitter Methods
+    // ==========================================================================
+    /**
+     * Emits a typed event with automatic context injection (trace, timestamp).
+     *
+     * @param event The event name (e.g., 'agent:execution:start')
+     * @param payload The event payload containing 'data' and optional context like 'correlationId'
+     */
+    emit(event, payload) {
+        const traceContext = index_js_1.Tracing.getContext();
+        const execContext = index_js_2.ExecutionContext.getOrUndefined();
+        // Construct the full event object matching the Zod schema
+        let fullEvent = {
+            type: event,
+            timestamp: new Date().toISOString(),
+            trace: {
+                traceId: traceContext?.traceId || `fallback-${Date.now()}`,
+                spanId: traceContext?.spanId || `fallback-${Date.now()}`,
+                parentSpanId: traceContext?.parentId,
+            },
+            correlationId: payload.correlationId,
+            executionId: payload.executionId ?? execContext?.executionId,
+            rootExecutionId: execContext?.rootExecutionId,
+            parentExecutionId: execContext?.parentExecutionId,
+            data: payload.data,
+        };
+        if (this.piiMasker) {
+            fullEvent = this.maskEventData(fullEvent);
+        }
+        // Best-effort export for Cloud materialization.
+        index_js_3.DomainEvents.publish(fullEvent);
+        return this.emitter.emit(event, fullEvent);
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        this.emitter.off(event, listener);
+        return this;
+    }
+    /**
+     * Recursively masks PII in the event payload
+     */
+    maskEventData(data) {
+        if (!this.piiMasker)
+            return data;
+        if (typeof data === "string") {
+            return this.piiMasker.mask(data);
+        }
+        if (Array.isArray(data)) {
+            return data.map(item => this.maskEventData(item));
+        }
+        if (typeof data === "object" && data !== null) {
+            if (data instanceof Date)
+                return data;
+            if (data instanceof Error) {
+                const maskedError = {
+                    name: data.name,
+                    message: this.maskEventData(data.message),
+                    stack: data.stack
+                };
+                return maskedError;
+            }
+            const maskedObj = {};
+            for (const key in data) {
+                if (Object.prototype.hasOwnProperty.call(data, key)) {
+                    maskedObj[key] = this.maskEventData(data[key]);
+                }
+            }
+            return maskedObj;
+        }
+        return data;
+    }
+}
+exports.BaseAgent = BaseAgent;

package/dist/agent/events/events.d.ts

@@ -0,0 +1,14 @@
+import { AgentExecutionStart, AgentExecutionEnd, AgentExecutionError, AgentLLMCall, AgentLLMResponse, AgentToolCall, AgentToolResult, ToolExecutionStart, ToolExecutionEnd, ToolExecutionError } from "../../events/schemas.js";
+export type AgentEventMap = {
+    "agent:execution:start": AgentExecutionStart;
+    "agent:execution:end": AgentExecutionEnd;
+    "agent:execution:error": AgentExecutionError;
+    "agent:llm:call": AgentLLMCall;
+    "agent:llm:response": AgentLLMResponse;
+    "agent:tool:call": AgentToolCall;
+    "agent:tool:result": AgentToolResult;
+    "tool:execution:start": ToolExecutionStart;
+    "tool:execution:end": ToolExecutionEnd;
+    "tool:execution:error": ToolExecutionError;
+};
+export type AgentEventName = keyof AgentEventMap;

package/dist/agent/events/events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/agent/events/events.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/events/events.spec.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Agent_js_1 = require("../Agent.js");
+const in_memory_js_1 = require("../memory/in-memory.js");
+const mock_provider_js_1 = require("../../__tests__/mocks/mock-provider.js");
+const schemas_js_1 = require("../../events/schemas.js");
+const Workflow_js_1 = require("../../workflow/Workflow.js");
+describe("Event Schema Compliance", () => {
+    it("should emit valid agent events matching the schema", async () => {
+        const memory = new in_memory_js_1.InMemory();
+        const provider = new mock_provider_js_1.MockProvider();
+        provider.enqueueResponse({
+            content: "Hello world",
+            usage: { promptTokens: 10, completionTokens: 5, totalTokens: 15 },
+        });
+        const agent = new Agent_js_1.Agent({
+            id: "schema-test-agent",
+            name: "schema-test-agent",
+            memory,
+            model: provider,
+            instructions: "Test instructions",
+        });
+        const events = [];
+        // BaseAgent emits the FULL event object including type
+        const collector = (event) => events.push(event);
+        // Attach listener to all known event types
+        const eventTypes = [
+            "agent:execution:start",
+            "agent:execution:end",
+            "agent:llm:call",
+            "agent:llm:response",
+        ];
+        eventTypes.forEach((type) => agent.on(type, collector));
+        await memory.addMessage({ role: "user", content: "Hi" });
+        await agent.execute();
+        expect(events.length).toBeGreaterThan(0);
+        events.forEach((event) => {
+            const result = schemas_js_1.NebulaEventSchema.safeParse(event);
+            if (!result.success) {
+                console.error(`Event validation failed for type '${event.type}':`, JSON.stringify(result.error.format(), null, 2));
+            }
+            expect(result.success).toBe(true);
+        });
+    });
+    it("should emit valid workflow events matching the schema", async () => {
+        const workflow = new Workflow_js_1.Workflow({
+            id: "schema-test-workflow",
+            name: "Schema Test",
+        });
+        workflow
+            .start("start", async ({ input }) => input)
+            .step("step1", async ({ input }) => `${input} processed`)
+            .finish("finish", async ({ input }) => input);
+        const events = [];
+        const collector = (event) => events.push(event);
+        const eventTypes = [
+            "workflow:run:start",
+            "workflow:run:end",
+            "workflow:run:error",
+            "workflow:node:start",
+            "workflow:node:end",
+        ];
+        // @ts-ignore - dynamic attachment
+        eventTypes.forEach((type) => workflow.on(type, collector));
+        await workflow.run("start");
+        expect(events.length).toBeGreaterThan(0);
+        events.forEach((event) => {
+            const result = schemas_js_1.NebulaEventSchema.safeParse(event);
+            if (!result.success) {
+                console.error(`Event validation failed for type '${event.type}':`, JSON.stringify(result.error.format(), null, 2));
+            }
+            expect(result.success).toBe(true);
+        });
+    });
+});

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

@@ -0,0 +1,23 @@
+interface IInstruction {
+    resolve(): Promise<string>;
+}
+export type InstructionVariables = Record<string, string | number | boolean>;
+export declare class Instruction implements IInstruction {
+    private content;
+    private variables;
+    constructor(content: string, variables?: InstructionVariables);
+    /**
+     * Resolve a instrução substituindo as variáveis.
+     */
+    resolve(): Promise<string>;
+    /**
+     * Cria uma instrução a partir de um arquivo de texto.
+     * Suporta caminhos absolutos ou relativos ao CWD.
+     */
+    static fromFile(filePath: string, variables?: InstructionVariables): Promise<Instruction>;
+    /**
+     * Cria uma instrução a partir de uma string direta.
+     */
+    static create(content: string, variables?: InstructionVariables): Instruction;
+}
+export {};

package/dist/agent/instruction/index.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Instruction = void 0;
+const fs = __importStar(require("fs/promises"));
+class Instruction {
+    content;
+    variables = {};
+    constructor(content, variables = {}) {
+        this.content = content;
+        this.variables = variables;
+    }
+    /**
+     * Resolve a instrução substituindo as variáveis.
+     */
+    async resolve() {
+        let resolved = this.content;
+        for (const [key, value] of Object.entries(this.variables)) {
+            // Substituição simples de {{key}}
+            resolved = resolved.replace(new RegExp(`{{\\s*${key}\\s*}}`, "g"), String(value));
+        }
+        return resolved;
+    }
+    /**
+     * Cria uma instrução a partir de um arquivo de texto.
+     * Suporta caminhos absolutos ou relativos ao CWD.
+     */
+    static async fromFile(filePath, variables = {}) {
+        try {
+            const content = await fs.readFile(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.
+     */
+    static create(content, variables = {}) {
+        return new Instruction(content, variables);
+    }
+}
+exports.Instruction = Instruction;

package/dist/agent/memory/in-memory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Basic in-memory implementation (default).
+ */
+import { IMemory, MemoryExecutionContext } from "./memory.js";
+import { Message } from "../provider/index.js";
+export declare class InMemory implements IMemory {
+    private options;
+    /** Partitioned message storage: memoryKey -> messages */
+    private partitions;
+    /** Partitioned state storage: memoryKey -> state map */
+    private statePartitions;
+    constructor(options?: {
+        maxMessages?: number;
+    });
+    private getPartitionKey;
+    private getOrCreatePartition;
+    private getOrCreateStateMap;
+    addMessage(message: Message, ctx?: MemoryExecutionContext): Promise<void>;
+    getMessages(ctx?: MemoryExecutionContext): Promise<Message[]>;
+    getState<T = unknown>(key: string, ctx?: MemoryExecutionContext): Promise<T | undefined>;
+    setState<T = unknown>(key: string, value: T, ctx?: MemoryExecutionContext): Promise<void>;
+    deleteState(key: string, ctx?: MemoryExecutionContext): Promise<void>;
+    clear(ctx?: MemoryExecutionContext): Promise<void>;
+}

package/dist/agent/memory/in-memory.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Basic in-memory implementation (default).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemory = void 0;
+/** Internal key for default (no context) storage */
+const DEFAULT_KEY = "__default__";
+class InMemory {
+    options;
+    /** Partitioned message storage: memoryKey -> messages */
+    partitions = new Map();
+    /** Partitioned state storage: memoryKey -> state map */
+    statePartitions = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    getPartitionKey(ctx) {
+        return ctx?.memoryKey ?? DEFAULT_KEY;
+    }
+    getOrCreatePartition(partitionKey) {
+        let messages = this.partitions.get(partitionKey);
+        if (!messages) {
+            messages = [];
+            this.partitions.set(partitionKey, messages);
+        }
+        return messages;
+    }
+    getOrCreateStateMap(partitionKey) {
+        let stateMap = this.statePartitions.get(partitionKey);
+        if (!stateMap) {
+            stateMap = new Map();
+            this.statePartitions.set(partitionKey, stateMap);
+        }
+        return stateMap;
+    }
+    async addMessage(message, ctx) {
+        const partitionKey = this.getPartitionKey(ctx);
+        const messages = this.getOrCreatePartition(partitionKey);
+        messages.push(message);
+        // Truncate if needed (keep latest N messages)
+        if (this.options.maxMessages && messages.length > this.options.maxMessages) {
+            const systemMessage = messages.find((m) => m.role === "system");
+            const removeCount = messages.length - this.options.maxMessages;
+            messages.splice(0, removeCount);
+            // Restore system message if lost
+            if (systemMessage && !messages.includes(systemMessage)) {
+                messages.unshift(systemMessage);
+            }
+        }
+    }
+    async getMessages(ctx) {
+        const partitionKey = this.getPartitionKey(ctx);
+        const messages = this.partitions.get(partitionKey);
+        return messages ? [...messages] : [];
+    }
+    async getState(key, ctx) {
+        const partitionKey = this.getPartitionKey(ctx);
+        const stateMap = this.statePartitions.get(partitionKey);
+        return stateMap?.get(key);
+    }
+    async setState(key, value, ctx) {
+        const partitionKey = this.getPartitionKey(ctx);
+        const stateMap = this.getOrCreateStateMap(partitionKey);
+        stateMap.set(key, value);
+    }
+    async deleteState(key, ctx) {
+        const partitionKey = this.getPartitionKey(ctx);
+        const stateMap = this.statePartitions.get(partitionKey);
+        stateMap?.delete(key);
+    }
+    async clear(ctx) {
+        const partitionKey = this.getPartitionKey(ctx);
+        this.partitions.delete(partitionKey);
+        this.statePartitions.delete(partitionKey);
+    }
+}
+exports.InMemory = InMemory;

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

@@ -0,0 +1,2 @@
+export * from "./memory.js";
+export * from "./in-memory.js";

package/dist/agent/memory/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./memory.js"), exports);
+__exportStar(require("./in-memory.js"), exports);

package/dist/agent/memory/memory.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Memory Interface
+ *
+ * Define como o Agente armazena e recupera o histórico de mensagens.
+ */
+import { Message } from "../provider/index.js";
+/**
+ * Execution context for memory partitioning.
+ * When provided, memory operations are scoped to the given memoryKey.
+ */
+export interface MemoryExecutionContext {
+    /** Required when context is used. Partitions memory by this key. */
+    memoryKey: string;
+    /** Extensible for future metadata. */
+    [key: string]: unknown;
+}
+export interface IMemory {
+    /**
+     * Adds a message to the conversation history.
+     * @param message The message to add
+     * @param ctx Optional execution context for memory partitioning
+     */
+    addMessage(message: Message, ctx?: MemoryExecutionContext): Promise<void>;
+    /**
+     * Returns the full conversation history.
+     * @param ctx Optional execution context for memory partitioning
+     */
+    getMessages(ctx?: MemoryExecutionContext): Promise<Message[]>;
+    /**
+     * Clears the conversation history.
+     * @param ctx Optional execution context for memory partitioning
+     */
+    clear(ctx?: MemoryExecutionContext): Promise<void>;
+    /**
+     * Optional key/value state storage for agents/teams.
+     * Useful for persisting lightweight orchestration state (e.g., handoff current agent).
+     * @param key State key
+     * @param ctx Optional execution context for memory partitioning
+     */
+    getState?<T = unknown>(key: string, ctx?: MemoryExecutionContext): Promise<T | undefined>;
+    setState?<T = unknown>(key: string, value: T, ctx?: MemoryExecutionContext): Promise<void>;
+    deleteState?(key: string, ctx?: MemoryExecutionContext): Promise<void>;
+}

package/dist/agent/memory/memory.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Memory Interface
+ *
+ * Define como o Agente armazena e recupera o histórico de mensagens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/agent/provider/file-parts.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/provider/file-parts.spec.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Agent_js_1 = require("../Agent.js");
+const index_js_1 = require("../memory/index.js");
+class NoopLogger {
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+}
+class StubModel {
+    providerName = "stub";
+    modelName = "stub-model";
+    capabilities;
+    constructor(caps) {
+        this.capabilities = caps;
+    }
+    async generate(_messages, _tools) {
+        return { content: "ok" };
+    }
+    async *generateStream(_messages, _tools) {
+        yield { type: "content_delta", delta: "ok" };
+        yield { type: "finish", reason: "stop" };
+    }
+}
+describe("File parts validation", () => {
+    it("throws when model does not declare file capabilities", async () => {
+        const agent = new Agent_js_1.Agent({
+            id: "test",
+            name: "test",
+            model: new StubModel(undefined),
+            memory: new index_js_1.InMemory({ maxMessages: 50 }),
+            instructions: "test",
+            logger: new NoopLogger(),
+        });
+        await agent.addMessage({
+            role: "user",
+            content: [
+                { type: "text", text: "analyze" },
+                {
+                    type: "file",
+                    file: {
+                        name: "a.pdf",
+                        mimeType: "application/pdf",
+                        source: { type: "url", url: "https://example.com/a.pdf", sizeBytes: 100 },
+                    },
+                },
+            ],
+        });
+        await expect(agent.execute()).rejects.toThrow("Model does not support file inputs");
+    });
+    it("throws when base64 file exceeds 10MB", async () => {
+        const agent = new Agent_js_1.Agent({
+            id: "test",
+            name: "test",
+            model: new StubModel({
+                inputFiles: { mimeTypes: "any", sources: ["base64", "url"] },
+            }),
+            memory: new index_js_1.InMemory({ maxMessages: 50 }),
+            instructions: "test",
+            logger: new NoopLogger(),
+        });
+        // Create base64 string slightly above 10MB (decoded)
+        const tenMbPlusOne = (10 * 1024 * 1024) + 1;
+        const base64Len = Math.ceil(tenMbPlusOne / 3) * 4; // inverse of decoded length approximation
+        const bigBase64 = "A".repeat(base64Len);
+        await agent.addMessage({
+            role: "user",
+            content: [
+                { type: "text", text: "analyze" },
+                {
+                    type: "file",
+                    file: {
+                        name: "big.bin",
+                        mimeType: "application/octet-stream",
+                        source: { type: "base64", base64: bigBase64 },
+                    },
+                },
+            ],
+        });
+        await expect(agent.execute()).rejects.toThrow("exceeds max size");
+    });
+});