@nebulaos/core 0.1.1

package/dist/tracing/index.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tracing = exports.ActiveSpan = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+// =============================================================================
+// ActiveSpan
+// =============================================================================
+class ActiveSpan {
+    traceId;
+    spanId;
+    parentSpanId;
+    kind;
+    name;
+    correlationId;
+    executionId;
+    exporter;
+    ended = false;
+    constructor(traceId, spanId, parentSpanId, kind, name, correlationId, executionId, exporter) {
+        this.traceId = traceId;
+        this.spanId = spanId;
+        this.parentSpanId = parentSpanId;
+        this.kind = kind;
+        this.name = name;
+        this.correlationId = correlationId;
+        this.executionId = executionId;
+        this.exporter = exporter;
+    }
+    async end(input) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        const event = {
+            v: 1,
+            type: "telemetry:span:end",
+            timestamp: new Date().toISOString(),
+            trace: {
+                traceId: this.traceId,
+                spanId: this.spanId,
+                parentSpanId: this.parentSpanId,
+            },
+            correlationId: this.correlationId,
+            executionId: this.executionId,
+            status: input.status,
+            span: {
+                kind: this.kind,
+                name: this.name,
+                // The contract expects a kind-specific shape, but we keep this generic here.
+                // The callers are responsible for providing kind-specific keys.
+                data: input.data,
+            },
+        };
+        try {
+            await this.exporter.exportBatch([event]);
+        }
+        catch {
+            // Telemetry must never break execution.
+        }
+    }
+    get isEnded() {
+        return this.ended;
+    }
+}
+exports.ActiveSpan = ActiveSpan;
+// =============================================================================
+// Internal helpers
+// =============================================================================
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** Generate a W3C-compliant trace ID (32 hex chars). */
+function generateTraceId() {
+    return (0, node_crypto_1.randomBytes)(16).toString("hex");
+}
+/** Generate a W3C-compliant span ID (16 hex chars). */
+function generateSpanId() {
+    return (0, node_crypto_1.randomBytes)(8).toString("hex");
+}
+class NoopTelemetryExporter {
+    async exportBatch(_events) {
+        // noop
+    }
+}
+// =============================================================================
+// Tracing (static facade)
+// =============================================================================
+class Tracing {
+    static exporter = new NoopTelemetryExporter();
+    static provider = null;
+    static setExporter(exporter) {
+        this.exporter = exporter;
+    }
+    /**
+     * Injects an external tracing provider (e.g. OpenTelemetry).
+     * When set, `getContext()` and `withSpan()` delegate to the provider
+     * so that span IDs originate from OTel and the hierarchy is preserved.
+     */
+    static setProvider(provider) {
+        this.provider = provider;
+    }
+    /**
+     * Gets the current trace context.
+     * Returns undefined if called outside of a traced execution.
+     */
+    static getContext() {
+        if (this.provider) {
+            return this.provider.getContext();
+        }
+        return storage.getStore();
+    }
+    /**
+     * Gets the current trace context or creates a dummy one if none exists.
+     * Useful for logging where you always want *some* ID.
+     */
+    static getContextOrDummy() {
+        const context = this.getContext();
+        if (context)
+            return context;
+        return {
+            traceId: "no-trace",
+            spanId: "no-span",
+        };
+    }
+    /**
+     * Runs a function inside a new telemetry span and exports span lifecycle events.
+     *
+     * When a provider is set, delegates entirely to the provider so that the
+     * span IDs come from the external tracing system (e.g. OpenTelemetry).
+     * Otherwise, falls back to the built-in implementation that uses the
+     * ITelemetryExporter.
+     */
+    static async withSpan(input, fn) {
+        if (this.provider) {
+            return this.provider.withSpan(input, fn);
+        }
+        return this.defaultWithSpan(input, fn);
+    }
+    // ---------------------------------------------------------------------------
+    // Default (built-in) implementation – used when no provider is set
+    // ---------------------------------------------------------------------------
+    static async defaultWithSpan(input, fn) {
+        const parent = storage.getStore();
+        const traceId = parent?.traceId ?? generateTraceId();
+        const parentSpanId = parent?.spanId;
+        const spanId = generateSpanId();
+        const startedAt = new Date().toISOString();
+        const startEvent = {
+            v: 1,
+            type: "telemetry:span:start",
+            timestamp: startedAt,
+            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 {
+            // Telemetry must never break execution.
+        }
+        const context = {
+            traceId,
+            spanId,
+            parentId: parentSpanId,
+        };
+        const activeSpan = new ActiveSpan(traceId, spanId, parentSpanId, input.kind, input.name, input.correlationId, input.executionId, this.exporter);
+        return storage.run(context, 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;
+            }
+        });
+    }
+}
+exports.Tracing = Tracing;

package/dist/tsup.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/tsup.config.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tsup_1 = require("tsup");
+exports.default = (0, tsup_1.defineConfig)({
+    entry: ["index.ts"],
+    format: ["cjs", "esm"],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+});

package/dist/utils/schema-to-zod.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export type SchemaDefinition = Record<string, string | z.ZodTypeAny>;
+export declare function schemaToZod(shape: SchemaDefinition): z.ZodObject<any, "strip", z.ZodTypeAny, {
+    [x: string]: any;
+}, {
+    [x: string]: any;
+}>;

package/dist/utils/schema-to-zod.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaToZod = schemaToZod;
+const zod_1 = require("zod");
+function schemaToZod(shape) {
+    const zodShape = {};
+    for (const [key, value] of Object.entries(shape)) {
+        if (typeof value === 'string') {
+            let schema = zod_1.z.any();
+            const isOptional = value.endsWith('?');
+            const type = isOptional ? value.slice(0, -1) : value;
+            switch (type) {
+                case 'string':
+                    schema = zod_1.z.string();
+                    break;
+                case 'number':
+                    schema = zod_1.z.number();
+                    break;
+                case 'boolean':
+                    schema = zod_1.z.boolean();
+                    break;
+                case 'array':
+                    schema = zod_1.z.array(zod_1.z.any());
+                    break; // Simplificado
+                default: schema = zod_1.z.any();
+            }
+            if (isOptional)
+                schema = schema.optional();
+            zodShape[key] = schema;
+        }
+        else {
+            zodShape[key] = value;
+        }
+    }
+    return zod_1.z.object(zodShape);
+}

package/dist/workflow/Workflow.d.ts

@@ -0,0 +1,106 @@
+import type { ZodSchema } from "zod";
+import type { Agent } from "../agent/Agent.js";
+import type { IWorkflowQueue, IWorkflowStateStore, RetryPolicy, WorkflowState } from "./adapters.js";
+import type { WorkflowEventMap, WorkflowEventName } from "./events.js";
+import type { WorkflowAgentNodeOptions, WorkflowNodeHandler, WorkflowRunOptions } from "./types.js";
+import type { WorkflowDefinition } from "./definition/types.js";
+import { SharedNodeNameRegistry } from "./graph/NodeNameRegistry.js";
+import type { InternalNode } from "./graph/nodes.js";
+export interface WorkflowConfig<Input = any, Output = any> {
+    id: string;
+    name?: string;
+    description?: string;
+    inputSchema?: ZodSchema<Input>;
+    outputSchema?: ZodSchema<Output>;
+    maxSteps?: number;
+    timeoutMs?: number;
+    stateStore?: IWorkflowStateStore;
+    queueAdapter?: IWorkflowQueue;
+    retryPolicy?: RetryPolicy;
+    logLevel?: "debug" | "info" | "warn" | "error" | "none";
+    /**
+     * @internal
+     * The root workflow ID for sub-workflows (parallel/branch).
+     * Used to ensure all events are emitted with the registered workflow ID.
+     */
+    rootWorkflowId?: string;
+}
+export declare class Workflow<Input = any, Output = any> {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    private readonly config;
+    private readonly emitter;
+    private readonly events;
+    private readonly graph;
+    private readonly stateService;
+    private readonly telemetry;
+    private readonly nodeExecutor;
+    private readonly runner;
+    private readonly queue;
+    private cachedDefinition?;
+    /**
+     * Returns the workflow ID to use for events and telemetry.
+     * For sub-workflows (parallel/branch), this returns the root workflow ID.
+     */
+    get registeredWorkflowId(): string;
+    constructor(config: WorkflowConfig<Input, Output>, internal?: {
+        registry?: SharedNodeNameRegistry;
+    });
+    /**
+     * Exports a stable workflow graph definition suitable for visualization.
+     */
+    describe(): WorkflowDefinition;
+    private allocateNodeId;
+    start<TOut = Input>(name: string, handler: WorkflowNodeHandler<Input, TOut>): this;
+    step<TIn = any, TOut = any>(name: string, handler: WorkflowNodeHandler<TIn, TOut>): this;
+    /**
+     * Adds an agent as a first-class node in the workflow graph.
+     */
+    agent(name: string, agent: Agent, options?: WorkflowAgentNodeOptions): this;
+    /**
+     * Branch node. The selector returns the branch key to execute.
+     */
+    branch<TIn = any>(name: string, selector: WorkflowNodeHandler<TIn, string>, branches: Record<string, (wf: Workflow<TIn, any>) => void>): this;
+    /**
+     * Parallel node. Executes multiple sub-workflows concurrently and returns an array of outputs.
+     */
+    parallel<TIn = any>(name: string, workflows: Array<(wf: Workflow<TIn, any>) => void>): this;
+    finish(name: string, handler: WorkflowNodeHandler<any, Output>): this;
+    on<E extends WorkflowEventName>(event: E, listener: (data: WorkflowEventMap[E]) => void): this;
+    once<E extends WorkflowEventName>(event: E, listener: (data: WorkflowEventMap[E]) => void): this;
+    off<E extends WorkflowEventName>(event: E, listener: (data: WorkflowEventMap[E]) => void): this;
+    run(input: Input, options?: WorkflowRunOptions): Promise<Output>;
+    enqueue(input: Input): Promise<{
+        executionId: string;
+    }>;
+    getStatus(executionId: string): Promise<{
+        status: WorkflowState["status"];
+        currentStep?: string;
+        progress?: number;
+    }>;
+    /**
+     * @internal
+     * Exposes the internal node list for definition traversal (read-only).
+     */
+    __internalNodes(): readonly InternalNode[];
+}
+/**
+ * @internal
+ * Exposes internal nodes for DefinitionBuilder (read-only).
+ */
+export interface WorkflowInternalAccess {
+    __internalNodes(): readonly InternalNode[];
+}
+/**
+ * @internal
+ * Used by DefinitionBuilder to traverse the graph without breaking encapsulation.
+ */
+export interface WorkflowInternalNodeAccess {
+    __internalNodes(): readonly InternalNode[];
+}
+export declare class WorkflowInternal {
+    static nodes(wf: Workflow<any, any>): readonly InternalNode[];
+}
+export type { WorkflowNodeHandler, WorkflowRunOptions, WorkflowAgentNodeOptions } from "./types.js";
+export type { WorkflowDefinition, WorkflowDefinitionNode, WorkflowDefinitionEdge, WorkflowNodeType, } from "./definition/types.js";

package/dist/workflow/Workflow.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowInternal = exports.Workflow = void 0;
+const node_events_1 = require("node:events");
+const index_js_1 = require("../logger/index.js");
+const DefinitionBuilder_js_1 = require("./definition/DefinitionBuilder.js");
+const DefinitionHasher_js_1 = require("./definition/DefinitionHasher.js");
+const NodeNameRegistry_js_1 = require("./graph/NodeNameRegistry.js");
+const WorkflowGraph_js_1 = require("./graph/WorkflowGraph.js");
+const WorkflowEventBus_js_1 = require("./execution/WorkflowEventBus.js");
+const WorkflowTelemetry_js_1 = require("./execution/WorkflowTelemetry.js");
+const WorkflowStateService_js_1 = require("./state/WorkflowStateService.js");
+const NodeExecutor_js_1 = require("./execution/NodeExecutor.js");
+const WorkflowRunner_js_1 = require("./execution/WorkflowRunner.js");
+const WorkflowQueueService_js_1 = require("./queue/WorkflowQueueService.js");
+// =============================================================================
+// Workflow
+// =============================================================================
+class Workflow {
+    id;
+    name;
+    description;
+    config;
+    emitter = new node_events_1.EventEmitter();
+    events = new WorkflowEventBus_js_1.WorkflowEventBus(this.emitter);
+    graph;
+    stateService;
+    telemetry = new WorkflowTelemetry_js_1.WorkflowTelemetry();
+    nodeExecutor = new NodeExecutor_js_1.NodeExecutor();
+    runner;
+    queue;
+    cachedDefinition;
+    /**
+     * Returns the workflow ID to use for events and telemetry.
+     * For sub-workflows (parallel/branch), this returns the root workflow ID.
+     */
+    get registeredWorkflowId() {
+        return this.config.rootWorkflowId ?? this.id;
+    }
+    constructor(config, internal) {
+        this.config = config;
+        this.id = config.id;
+        this.name = config.name;
+        this.description = config.description;
+        const registry = internal?.registry ?? new NodeNameRegistry_js_1.SharedNodeNameRegistry();
+        this.graph = new WorkflowGraph_js_1.WorkflowGraph(registry);
+        this.stateService = new WorkflowStateService_js_1.WorkflowStateService(this.config.stateStore);
+        this.runner = new WorkflowRunner_js_1.WorkflowRunner(this.config, this.events, this.telemetry, this.stateService, this.nodeExecutor);
+        this.queue = new WorkflowQueueService_js_1.WorkflowQueueService(this.config.queueAdapter, this.stateService);
+        if (this.config.logLevel && this.config.logLevel !== "none") {
+            const logger = new index_js_1.ConsoleLogger(this.config.logLevel);
+            new index_js_1.WorkflowLogger(this, logger);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Definition / builder
+    // ---------------------------------------------------------------------------
+    /**
+     * Exports a stable workflow graph definition suitable for visualization.
+     */
+    describe() {
+        if (this.cachedDefinition)
+            return this.cachedDefinition;
+        const builder = new DefinitionBuilder_js_1.DefinitionBuilder();
+        const { nodes, edges } = builder.build(this);
+        const version = new DefinitionHasher_js_1.DefinitionHasher().hash({ workflowId: this.id, nodes, edges });
+        this.cachedDefinition = {
+            workflowId: this.id,
+            name: this.name,
+            description: this.description,
+            version,
+            nodes,
+            edges,
+        };
+        return this.cachedDefinition;
+    }
+    allocateNodeId(name) {
+        // Invalidate cached definition on any mutation.
+        this.cachedDefinition = undefined;
+        return this.graph.allocateId(name);
+    }
+    start(name, handler) {
+        const { id, displayName } = this.allocateNodeId(name);
+        this.graph.add({ id, displayName, type: "start", handler });
+        return this;
+    }
+    step(name, handler) {
+        const { id, displayName } = this.allocateNodeId(name);
+        this.graph.add({ id, displayName, type: "step", handler });
+        return this;
+    }
+    /**
+     * Adds an agent as a first-class node in the workflow graph.
+     */
+    agent(name, agent, options) {
+        const { id, displayName } = this.allocateNodeId(name);
+        this.graph.add({ id, displayName, type: "agent", agent, toInput: options?.toInput });
+        return this;
+    }
+    /**
+     * Branch node. The selector returns the branch key to execute.
+     */
+    branch(name, selector, branches) {
+        const { id, displayName } = this.allocateNodeId(name);
+        const branchWorkflows = {};
+        for (const [key, build] of Object.entries(branches)) {
+            const wf = new Workflow({ id: `${this.id}/branch/${key}`, rootWorkflowId: this.registeredWorkflowId }, { registry: this.graph.getRegistry() });
+            build(wf);
+            branchWorkflows[key] = wf;
+        }
+        this.graph.add({ id, displayName, type: "branch", selector, branches: branchWorkflows });
+        return this;
+    }
+    /**
+     * Parallel node. Executes multiple sub-workflows concurrently and returns an array of outputs.
+     */
+    parallel(name, workflows) {
+        const { id, displayName } = this.allocateNodeId(name);
+        const parallelWorkflows = workflows.map((build, index) => {
+            const wf = new Workflow({ id: `${this.id}/parallel/${index}`, rootWorkflowId: this.registeredWorkflowId }, { registry: this.graph.getRegistry() });
+            build(wf);
+            return wf;
+        });
+        this.graph.add({ id, displayName, type: "parallel", workflows: parallelWorkflows });
+        return this;
+    }
+    finish(name, handler) {
+        const { id, displayName } = this.allocateNodeId(name);
+        this.graph.add({ id, displayName, type: "finish", handler });
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    // Event API
+    // ---------------------------------------------------------------------------
+    on(event, listener) {
+        this.events.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        this.events.once(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        this.events.off(event, listener);
+        return this;
+    }
+    // ---------------------------------------------------------------------------
+    // Execution
+    // ---------------------------------------------------------------------------
+    async run(input, options = {}) {
+        if (this.config.inputSchema) {
+            const parsed = this.config.inputSchema.safeParse(input);
+            if (!parsed.success)
+                throw new Error(`Input validation failed: ${parsed.error.message}`);
+        }
+        const definition = this.describe();
+        const out = await this.runner.run({
+            workflowId: this.registeredWorkflowId,
+            workflowNameForTelemetry: `workflow:${this.id}`,
+            definition,
+            nodes: this.graph.list(),
+            input,
+            options,
+        });
+        return out;
+    }
+    // ---------------------------------------------------------------------------
+    // Queue (placeholder adapter wiring)
+    // ---------------------------------------------------------------------------
+    async enqueue(input) {
+        const definition = this.describe();
+        return this.queue.enqueue({
+            workflowId: this.registeredWorkflowId,
+            definition,
+            nodes: this.graph.list(),
+            rawInput: input,
+        });
+    }
+    async getStatus(executionId) {
+        if (this.config.queueAdapter?.getStatus)
+            return this.config.queueAdapter.getStatus(executionId);
+        if (!this.config.stateStore)
+            throw new Error("Queue adapter or state store is required for getStatus()");
+        const state = await this.config.stateStore.load(executionId);
+        if (!state)
+            throw new Error(`Execution ${executionId} not found`);
+        return { status: state.status, currentStep: state.currentNodeId, progress: undefined };
+    }
+    /**
+     * @internal
+     * Exposes the internal node list for definition traversal (read-only).
+     */
+    __internalNodes() {
+        return this.graph.list();
+    }
+}
+exports.Workflow = Workflow;
+// Implementation for internal access (kept public but marked @internal)
+class WorkflowInternal {
+    static nodes(wf) {
+        return wf.__internalNodes();
+    }
+}
+exports.WorkflowInternal = WorkflowInternal;

package/dist/workflow/adapters.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Workflow Adapters - Interfaces for State and Queue management
+ */
+export interface WorkflowState {
+    workflowId: string;
+    executionId: string;
+    definitionVersion: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'truncated';
+    currentNodeId?: string;
+    nodeStates: Record<string, {
+        status: 'pending' | 'running' | 'success' | 'error';
+        startedAt?: Date;
+        endedAt?: Date;
+        durationMs?: number;
+        attempt?: number;
+        input?: any;
+        output?: any;
+        error?: string;
+    }>;
+    input: any;
+    output?: any;
+    startedAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+    error?: string;
+    retryCount?: number;
+}
+export interface IWorkflowStateStore {
+    save(executionId: string, state: WorkflowState): Promise<void>;
+    load(executionId: string): Promise<WorkflowState | null>;
+    delete(executionId: string): Promise<void>;
+    listActive(workflowId?: string): Promise<string[]>;
+}
+export interface WorkflowJob {
+    executionId: string;
+    workflowId: string;
+    nodeId: string;
+    nodeName: string;
+    input: any;
+    attempt: number;
+    createdAt: Date;
+}
+export interface IWorkflowQueue {
+    enqueue(job: WorkflowJob): Promise<void>;
+    process(handler: (job: WorkflowJob) => Promise<void>): void;
+    close(): Promise<void>;
+    getStatus?(executionId: string): Promise<{
+        status: WorkflowState['status'];
+        currentStep?: string;
+        progress?: number;
+    }>;
+}
+export interface RetryPolicy {
+    maxAttempts: number;
+    backoff: 'exponential' | 'linear' | 'fixed';
+    initialDelay: number;
+    maxDelay?: number;
+    retryableErrors?: string[];
+}
+export declare function calculateRetryDelay(policy: RetryPolicy, attempt: number): number;
+export declare function isRetryableError(error: Error, policy: RetryPolicy): boolean;

package/dist/workflow/adapters.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Workflow Adapters - Interfaces for State and Queue management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateRetryDelay = calculateRetryDelay;
+exports.isRetryableError = isRetryableError;
+function calculateRetryDelay(policy, attempt) {
+    const { backoff, initialDelay, maxDelay = 60000 } = policy;
+    let delay;
+    switch (backoff) {
+        case 'exponential':
+            delay = initialDelay * Math.pow(2, attempt - 1);
+            break;
+        case 'linear':
+            delay = initialDelay * attempt;
+            break;
+        case 'fixed':
+        default:
+            delay = initialDelay;
+    }
+    return Math.min(delay, maxDelay);
+}
+function isRetryableError(error, policy) {
+    if (!policy.retryableErrors || policy.retryableErrors.length === 0) {
+        return true;
+    }
+    return policy.retryableErrors.some((pattern) => error.message.includes(pattern) || error.name.includes(pattern));
+}

package/dist/workflow/definition/DefinitionBuilder.d.ts

@@ -0,0 +1,9 @@
+import type { Workflow } from "../Workflow.js";
+import type { WorkflowDefinitionEdge, WorkflowDefinitionNode } from "./types.js";
+export declare class DefinitionBuilder {
+    build(root: Workflow<any, any>): {
+        nodes: WorkflowDefinitionNode[];
+        edges: WorkflowDefinitionEdge[];
+    };
+    private findTerminalNodeIds;
+}