@nebulaos/core 0.1.1

package/dist/events/schemas.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NebulaEventSchema = exports.ExecutionCostIncurredSchema = exports.ToolExecutionErrorSchema = exports.ToolExecutionEndSchema = exports.ToolExecutionStartSchema = exports.WorkflowNodeEndSchema = exports.WorkflowNodeStartSchema = exports.WorkflowRunErrorSchema = exports.WorkflowRunEndSchema = exports.WorkflowRunStartSchema = exports.AgentToolResultSchema = exports.AgentToolCallSchema = exports.AgentLLMResponseSchema = exports.AgentLLMCallSchema = exports.AgentExecutionErrorSchema = exports.AgentExecutionEndSchema = exports.AgentExecutionStartSchema = exports.ModelSchema = exports.ErrorSchema = exports.UsageSchema = exports.EventCommonSchema = exports.TraceContextSchema = void 0;
+const zod_1 = require("zod");
+// =============================================================================
+// Common Fields
+// =============================================================================
+exports.TraceContextSchema = zod_1.z.object({
+    traceId: zod_1.z.string().describe("Unique identifier for the trace"),
+    spanId: zod_1.z.string().describe("Unique identifier for the current span"),
+    parentSpanId: zod_1.z.string().optional().describe("Identifier of the parent span, if any"),
+});
+exports.EventCommonSchema = zod_1.z.object({
+    type: zod_1.z.string().describe("Event type identifier (e.g., 'agent:execution:start')"),
+    timestamp: zod_1.z.string().datetime().describe("ISO 8601 timestamp of when the event occurred"),
+    trace: exports.TraceContextSchema,
+    correlationId: zod_1.z.string().optional().describe("Optional external correlation ID"),
+    executionId: zod_1.z.string().optional().describe("Logical execution ID"),
+    rootExecutionId: zod_1.z.string().optional().describe("Top-level (root) execution ID"),
+    parentExecutionId: zod_1.z.string().optional().describe("Immediate parent execution ID"),
+});
+exports.UsageSchema = zod_1.z.object({
+    promptTokens: zod_1.z.number(),
+    completionTokens: zod_1.z.number(),
+    totalTokens: zod_1.z.number(),
+    reasoningTokens: zod_1.z.number().optional(),
+});
+exports.ErrorSchema = zod_1.z.object({
+    name: zod_1.z.string().optional(),
+    message: zod_1.z.string(),
+    code: zod_1.z.string().optional(),
+    stack: zod_1.z.string().optional(),
+    details: zod_1.z.any().optional(),
+});
+exports.ModelSchema = zod_1.z.object({
+    provider: zod_1.z.string(),
+    model: zod_1.z.string(),
+    temperature: zod_1.z.number().optional(),
+    maxTokens: zod_1.z.number().optional(),
+    topP: zod_1.z.number().optional(),
+    frequencyPenalty: zod_1.z.number().optional(),
+    presencePenalty: zod_1.z.number().optional(),
+}).passthrough(); // Allow any other provider-specific config
+// =============================================================================
+// Agent Events
+// =============================================================================
+exports.AgentExecutionStartSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:execution:start"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        input: zod_1.z.any().optional().describe("Input arguments for the execution"),
+        metadata: zod_1.z.record(zod_1.z.any()).optional(),
+    }),
+});
+exports.AgentExecutionEndSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:execution:end"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        status: zod_1.z.enum(["success", "error", "truncated"]),
+        output: zod_1.z.any().optional().describe("Final output of the execution"),
+        durationMs: zod_1.z.number(),
+        usage: exports.UsageSchema.optional().describe("Total token usage for this execution"),
+    }),
+});
+exports.AgentExecutionErrorSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:execution:error"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        error: exports.ErrorSchema,
+        durationMs: zod_1.z.number().optional(),
+    }),
+});
+exports.AgentLLMCallSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:llm:call"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        step: zod_1.z.number().int().positive().describe("Current execution step"),
+        model: exports.ModelSchema,
+        messages: zod_1.z.array(zod_1.z.any()).describe("Messages sent to the LLM"),
+        tools: zod_1.z.array(zod_1.z.any()).optional().describe("Tools definitions sent to the LLM"),
+        responseFormat: zod_1.z.any().optional(),
+    }),
+});
+exports.AgentLLMResponseSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:llm:response"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        step: zod_1.z.number().int().positive(),
+        model: exports.ModelSchema,
+        content: zod_1.z.any().describe("Content returned by the LLM"),
+        toolCalls: zod_1.z.array(zod_1.z.any()).optional(),
+        finishReason: zod_1.z.string().optional(),
+        usage: exports.UsageSchema.optional(),
+        durationMs: zod_1.z.number().optional(),
+    }),
+});
+exports.AgentToolCallSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:tool:call"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        toolName: zod_1.z.string(),
+        toolCallId: zod_1.z.string(),
+        args: zod_1.z.any().describe("Arguments passed to the tool"),
+    }),
+});
+exports.AgentToolResultSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("agent:tool:result"),
+    data: zod_1.z.object({
+        agentId: zod_1.z.string().describe("Stable agent identifier (usually matches runtimeResourceId)"),
+        agentName: zod_1.z.string(),
+        toolName: zod_1.z.string(),
+        toolCallId: zod_1.z.string(),
+        output: zod_1.z.any().optional().describe("Result returned by the tool"),
+        error: zod_1.z.string().optional().describe("Error message if tool failed"),
+        durationMs: zod_1.z.number().optional(),
+    }),
+});
+// =============================================================================
+// Workflow Events
+// =============================================================================
+exports.WorkflowRunStartSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("workflow:run:start"),
+    data: zod_1.z.object({
+        workflowId: zod_1.z.string(),
+        definitionVersion: zod_1.z.string(),
+        input: zod_1.z.any().optional(),
+        metadata: zod_1.z.record(zod_1.z.any()).optional(),
+    }),
+});
+exports.WorkflowRunEndSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("workflow:run:end"),
+    data: zod_1.z.object({
+        workflowId: zod_1.z.string(),
+        definitionVersion: zod_1.z.string(),
+        status: zod_1.z.enum(["success", "error", "truncated"]),
+        output: zod_1.z.any().optional(),
+        durationMs: zod_1.z.number(),
+    }),
+});
+exports.WorkflowRunErrorSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("workflow:run:error"),
+    data: zod_1.z.object({
+        workflowId: zod_1.z.string(),
+        definitionVersion: zod_1.z.string(),
+        error: exports.ErrorSchema,
+        durationMs: zod_1.z.number().optional(),
+    }),
+});
+exports.WorkflowNodeStartSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("workflow:node:start"),
+    data: zod_1.z.object({
+        workflowId: zod_1.z.string(),
+        nodeId: zod_1.z.string(),
+        nodeType: zod_1.z.enum(["start", "step", "agent", "branch", "parallel", "finish"]),
+        attempt: zod_1.z.number().int().positive().default(1),
+        input: zod_1.z.any().optional(),
+    }),
+});
+exports.WorkflowNodeEndSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("workflow:node:end"),
+    data: zod_1.z.object({
+        workflowId: zod_1.z.string(),
+        nodeId: zod_1.z.string(),
+        nodeType: zod_1.z.enum(["start", "step", "agent", "branch", "parallel", "finish"]),
+        attempt: zod_1.z.number().int().positive().default(1),
+        status: zod_1.z.enum(["success", "error"]),
+        durationMs: zod_1.z.number(),
+        output: zod_1.z.any().optional(),
+        error: exports.ErrorSchema.optional(),
+    }),
+});
+// =============================================================================
+// Tool Execution Events (first-class executions)
+// =============================================================================
+exports.ToolExecutionStartSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("tool:execution:start"),
+    data: zod_1.z.object({
+        toolId: zod_1.z.string().describe("Stable tool identifier (matches runtimeResourceId)"),
+        toolName: zod_1.z.string().describe("Tool name (usually same as toolId)"),
+        toolCallId: zod_1.z.string().optional().describe("Underlying LLM tool call id, when applicable"),
+        input: zod_1.z.any().optional().describe("Raw tool input"),
+    }),
+});
+exports.ToolExecutionEndSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("tool:execution:end"),
+    data: zod_1.z.object({
+        toolId: zod_1.z.string().describe("Stable tool identifier (matches runtimeResourceId)"),
+        toolName: zod_1.z.string().describe("Tool name (usually same as toolId)"),
+        toolCallId: zod_1.z.string().optional(),
+        status: zod_1.z.enum(["success", "error"]),
+        output: zod_1.z.any().optional().describe("Tool output (may be non-JSON)"),
+        durationMs: zod_1.z.number(),
+    }),
+});
+exports.ToolExecutionErrorSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("tool:execution:error"),
+    data: zod_1.z.object({
+        toolId: zod_1.z.string().describe("Stable tool identifier (matches runtimeResourceId)"),
+        toolName: zod_1.z.string().describe("Tool name (usually same as toolId)"),
+        toolCallId: zod_1.z.string().optional(),
+        error: exports.ErrorSchema,
+        durationMs: zod_1.z.number().optional(),
+    }),
+});
+// =============================================================================
+// Execution Cost Events
+// =============================================================================
+exports.ExecutionCostIncurredSchema = exports.EventCommonSchema.extend({
+    type: zod_1.z.literal("execution:cost:incurred"),
+    data: zod_1.z.object({
+        amount: zod_1.z.string(),
+        description: zod_1.z.string().optional(),
+        source: zod_1.z.string().optional(),
+        idempotencyKey: zod_1.z.string().optional(),
+        metadata: zod_1.z.record(zod_1.z.any()).optional(),
+    }),
+});
+// =============================================================================
+// Discriminated Union
+// =============================================================================
+exports.NebulaEventSchema = zod_1.z.discriminatedUnion("type", [
+    exports.AgentExecutionStartSchema,
+    exports.AgentExecutionEndSchema,
+    exports.AgentExecutionErrorSchema,
+    exports.AgentLLMCallSchema,
+    exports.AgentLLMResponseSchema,
+    exports.AgentToolCallSchema,
+    exports.AgentToolResultSchema,
+    exports.WorkflowRunStartSchema,
+    exports.WorkflowRunEndSchema,
+    exports.WorkflowRunErrorSchema,
+    exports.WorkflowNodeStartSchema,
+    exports.WorkflowNodeEndSchema,
+    exports.ToolExecutionStartSchema,
+    exports.ToolExecutionEndSchema,
+    exports.ToolExecutionErrorSchema,
+    exports.ExecutionCostIncurredSchema,
+]);

package/dist/execution-context/index.d.ts

@@ -0,0 +1,21 @@
+export interface ExecutionContextState {
+    /**
+     * Current logical execution id.
+     * For top-level runs triggered by Cloud, this is the Cloud Execution.id.
+     * For sub-executions, this is a new stable UUID.
+     */
+    executionId: string;
+    /**
+     * Root execution id (top-level).
+     */
+    rootExecutionId: string;
+    /**
+     * Immediate parent execution id (nullable for root executions).
+     */
+    parentExecutionId?: string;
+}
+export declare class ExecutionContext {
+    static get(): ExecutionContextState | undefined;
+    static getOrUndefined(): ExecutionContextState | undefined;
+    static run<T>(ctx: ExecutionContextState, fn: () => Promise<T>): Promise<T>;
+}

package/dist/execution-context/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+class ExecutionContext {
+    static get() {
+        return storage.getStore();
+    }
+    static getOrUndefined() {
+        return storage.getStore();
+    }
+    static run(ctx, fn) {
+        return storage.run(ctx, fn);
+    }
+}
+exports.ExecutionContext = ExecutionContext;