@nebulaos/core 0.1.1

package/dist/multi-agent/types/index.d.ts

@@ -0,0 +1,349 @@
+import { z } from "zod";
+import type { Agent } from "../../agent/Agent.js";
+import type { IMemory } from "../../agent/memory/index.js";
+import type { IModel } from "../../agent/provider/index.js";
+/**
+ * Additional prompt used to steer coordination/selection/transfer,
+ * not to rewrite the underlying agent instructions.
+ */
+export type AdditionalPrompt = string;
+/**
+ * Memory configuration for delegation (AgentAsTool).
+ */
+export type DelegationMemoryConfig = {
+    type: "shared";
+} | {
+    type: "isolated";
+} | {
+    type: "custom";
+    memory: IMemory;
+};
+/**
+ * Edge definition for handoff graphs.
+ */
+export type HandoffEdge = {
+    from: Agent;
+    to: Agent;
+    toolId: string;
+    description?: string;
+};
+/**
+ * RouterTeam configuration.
+ */
+export type RouterTeamConfig = {
+    id: string;
+    name: string;
+    model: IModel;
+    children: Agent[];
+    fallback?: Agent;
+    memory?: IMemory;
+    additionalPrompt?: AdditionalPrompt;
+    maxRetries?: number;
+    timeoutMs?: number;
+};
+/**
+ * HandoffTeam configuration.
+ */
+export type HandoffTeamConfig = {
+    id: string;
+    name: string;
+    agents: Agent[];
+    edges: HandoffEdge[];
+    initialAgent: Agent;
+    memory?: IMemory;
+    additionalPrompt?: AdditionalPrompt;
+    maxTransfers?: number;
+    timeoutMs?: number;
+    tokenBudget?: number;
+    allowedTransitions?: Record<string, string[]>;
+    onTransfer?: (from: Agent, to: Agent) => void | Promise<void>;
+};
+/**
+ * AgentAsTool configuration.
+ */
+export type AgentAsToolConfig = {
+    agent: Agent;
+    id?: string;
+    description?: string;
+    additionalPrompt?: AdditionalPrompt;
+    memory?: DelegationMemoryConfig;
+    inputSchema?: z.ZodSchema;
+};
+/**
+ * Aggregation strategies for committee-like behavior.
+ */
+export type AggregationStrategy = "vote" | "summarize" | "confidence" | "first";
+/**
+ * HierarchicalTeam configuration.
+ */
+export type HierarchicalTeamConfig = {
+    id: string;
+    name: string;
+    manager: Agent;
+    workers: Agent[];
+    memory?: IMemory;
+    additionalPrompt?: AdditionalPrompt;
+    allowHandoff?: boolean;
+    workerCollaboration?: boolean;
+};
+/**
+ * PipelineTeam configuration.
+ */
+export type PipelineTeamConfig = {
+    id: string;
+    name: string;
+    stages: Agent[];
+    memory?: IMemory;
+    additionalPrompt?: AdditionalPrompt;
+};
+/**
+ * CommitteeTeam configuration.
+ */
+export type CommitteeTeamConfig = {
+    id: string;
+    name: string;
+    coordinator: Agent;
+    members: Agent[];
+    strategy: AggregationStrategy;
+    memory?: IMemory;
+    additionalPrompt?: AdditionalPrompt;
+    parallel?: boolean;
+};
+export declare const delegationMemorySchema: z.ZodUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"shared">;
+}, "strip", z.ZodTypeAny, {
+    type: "shared";
+}, {
+    type: "shared";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"isolated">;
+}, "strip", z.ZodTypeAny, {
+    type: "isolated";
+}, {
+    type: "isolated";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"custom">;
+    memory: z.ZodAny;
+}, "strip", z.ZodTypeAny, {
+    type: "custom";
+    memory?: any;
+}, {
+    type: "custom";
+    memory?: any;
+}>]>;
+export declare const handoffEdgeSchema: z.ZodObject<{
+    from: z.ZodAny;
+    to: z.ZodAny;
+    toolId: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    toolId: string;
+    description?: string | undefined;
+    from?: any;
+    to?: any;
+}, {
+    toolId: string;
+    description?: string | undefined;
+    from?: any;
+    to?: any;
+}>;
+export declare const routerTeamConfigSchema: z.ZodObject<{
+    model: z.ZodAny;
+    children: z.ZodArray<z.ZodAny, "many">;
+    fallback: z.ZodOptional<z.ZodAny>;
+    memory: z.ZodOptional<z.ZodAny>;
+    additionalPrompt: z.ZodOptional<z.ZodString>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    children: any[];
+    model?: any;
+    memory?: any;
+    fallback?: any;
+    additionalPrompt?: string | undefined;
+    maxRetries?: number | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    children: any[];
+    model?: any;
+    memory?: any;
+    fallback?: any;
+    additionalPrompt?: string | undefined;
+    maxRetries?: number | undefined;
+    timeoutMs?: number | undefined;
+}>;
+export declare const handoffTeamConfigSchema: z.ZodObject<{
+    agents: z.ZodArray<z.ZodAny, "many">;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodAny;
+        to: z.ZodAny;
+        toolId: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        toolId: string;
+        description?: string | undefined;
+        from?: any;
+        to?: any;
+    }, {
+        toolId: string;
+        description?: string | undefined;
+        from?: any;
+        to?: any;
+    }>, "many">;
+    initialAgent: z.ZodAny;
+    memory: z.ZodOptional<z.ZodAny>;
+    additionalPrompt: z.ZodOptional<z.ZodString>;
+    maxTransfers: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    tokenBudget: z.ZodOptional<z.ZodNumber>;
+    allowedTransitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    onTransfer: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    edges: {
+        toolId: string;
+        description?: string | undefined;
+        from?: any;
+        to?: any;
+    }[];
+    agents: any[];
+    memory?: any;
+    additionalPrompt?: string | undefined;
+    timeoutMs?: number | undefined;
+    initialAgent?: any;
+    maxTransfers?: number | undefined;
+    tokenBudget?: number | undefined;
+    allowedTransitions?: Record<string, string[]> | undefined;
+    onTransfer?: ((...args: unknown[]) => unknown) | undefined;
+}, {
+    edges: {
+        toolId: string;
+        description?: string | undefined;
+        from?: any;
+        to?: any;
+    }[];
+    agents: any[];
+    memory?: any;
+    additionalPrompt?: string | undefined;
+    timeoutMs?: number | undefined;
+    initialAgent?: any;
+    maxTransfers?: number | undefined;
+    tokenBudget?: number | undefined;
+    allowedTransitions?: Record<string, string[]> | undefined;
+    onTransfer?: ((...args: unknown[]) => unknown) | undefined;
+}>;
+export declare const agentAsToolConfigSchema: z.ZodObject<{
+    agent: z.ZodAny;
+    id: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    additionalPrompt: z.ZodOptional<z.ZodString>;
+    memory: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"shared">;
+    }, "strip", z.ZodTypeAny, {
+        type: "shared";
+    }, {
+        type: "shared";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"isolated">;
+    }, "strip", z.ZodTypeAny, {
+        type: "isolated";
+    }, {
+        type: "isolated";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"custom">;
+        memory: z.ZodAny;
+    }, "strip", z.ZodTypeAny, {
+        type: "custom";
+        memory?: any;
+    }, {
+        type: "custom";
+        memory?: any;
+    }>]>>;
+    inputSchema: z.ZodOptional<z.ZodType<z.ZodType<any, z.ZodTypeDef, any>, z.ZodTypeDef, z.ZodType<any, z.ZodTypeDef, any>>>;
+}, "strip", z.ZodTypeAny, {
+    agent?: any;
+    description?: string | undefined;
+    id?: string | undefined;
+    memory?: {
+        type: "shared";
+    } | {
+        type: "isolated";
+    } | {
+        type: "custom";
+        memory?: any;
+    } | undefined;
+    additionalPrompt?: string | undefined;
+    inputSchema?: z.ZodType<any, z.ZodTypeDef, any> | undefined;
+}, {
+    agent?: any;
+    description?: string | undefined;
+    id?: string | undefined;
+    memory?: {
+        type: "shared";
+    } | {
+        type: "isolated";
+    } | {
+        type: "custom";
+        memory?: any;
+    } | undefined;
+    additionalPrompt?: string | undefined;
+    inputSchema?: z.ZodType<any, z.ZodTypeDef, any> | undefined;
+}>;
+export declare const hierarchicalTeamConfigSchema: z.ZodObject<{
+    manager: z.ZodAny;
+    workers: z.ZodArray<z.ZodAny, "many">;
+    memory: z.ZodOptional<z.ZodAny>;
+    additionalPrompt: z.ZodOptional<z.ZodString>;
+    allowHandoff: z.ZodOptional<z.ZodBoolean>;
+    workerCollaboration: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    workers: any[];
+    memory?: any;
+    additionalPrompt?: string | undefined;
+    manager?: any;
+    allowHandoff?: boolean | undefined;
+    workerCollaboration?: boolean | undefined;
+}, {
+    workers: any[];
+    memory?: any;
+    additionalPrompt?: string | undefined;
+    manager?: any;
+    allowHandoff?: boolean | undefined;
+    workerCollaboration?: boolean | undefined;
+}>;
+export declare const pipelineTeamConfigSchema: z.ZodObject<{
+    stages: z.ZodArray<z.ZodAny, "many">;
+    memory: z.ZodOptional<z.ZodAny>;
+    additionalPrompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    stages: any[];
+    memory?: any;
+    additionalPrompt?: string | undefined;
+}, {
+    stages: any[];
+    memory?: any;
+    additionalPrompt?: string | undefined;
+}>;
+export declare const committeeTeamConfigSchema: z.ZodObject<{
+    coordinator: z.ZodAny;
+    members: z.ZodArray<z.ZodAny, "many">;
+    strategy: z.ZodEnum<["vote", "summarize", "confidence", "first"]>;
+    memory: z.ZodOptional<z.ZodAny>;
+    additionalPrompt: z.ZodOptional<z.ZodString>;
+    parallel: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    members: any[];
+    strategy: "vote" | "summarize" | "confidence" | "first";
+    parallel?: boolean | undefined;
+    memory?: any;
+    additionalPrompt?: string | undefined;
+    coordinator?: any;
+}, {
+    members: any[];
+    strategy: "vote" | "summarize" | "confidence" | "first";
+    parallel?: boolean | undefined;
+    memory?: any;
+    additionalPrompt?: string | undefined;
+    coordinator?: any;
+}>;
+export declare const aggregationStrategySchema: z.ZodEnum<["vote", "summarize", "confidence", "first"]>;
+export type { AgentAsToolConfig as AgentAsToolConfigType, RouterTeamConfig as RouterTeamConfigType, HandoffTeamConfig as HandoffTeamConfigType, HierarchicalTeamConfig as HierarchicalTeamConfigType, PipelineTeamConfig as PipelineTeamConfigType, CommitteeTeamConfig as CommitteeTeamConfigType, };

package/dist/multi-agent/types/index.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregationStrategySchema = exports.committeeTeamConfigSchema = exports.pipelineTeamConfigSchema = exports.hierarchicalTeamConfigSchema = exports.agentAsToolConfigSchema = exports.handoffTeamConfigSchema = exports.routerTeamConfigSchema = exports.handoffEdgeSchema = exports.delegationMemorySchema = void 0;
+const zod_1 = require("zod");
+// =============================================================================
+// Zod Schemas (runtime validation helpers)
+// =============================================================================
+const agentRef = zod_1.z.any(); // We avoid instanceof checks to prevent circular deps in runtime.
+const memoryRef = zod_1.z.any();
+exports.delegationMemorySchema = zod_1.z.union([
+    zod_1.z.object({ type: zod_1.z.literal("shared") }),
+    zod_1.z.object({ type: zod_1.z.literal("isolated") }),
+    zod_1.z.object({
+        type: zod_1.z.literal("custom"),
+        memory: memoryRef,
+    }),
+]);
+exports.handoffEdgeSchema = zod_1.z.object({
+    from: agentRef,
+    to: agentRef,
+    toolId: zod_1.z.string(),
+    description: zod_1.z.string().optional(),
+});
+exports.routerTeamConfigSchema = zod_1.z.object({
+    model: zod_1.z.any(),
+    children: zod_1.z.array(agentRef).min(1),
+    fallback: agentRef.optional(),
+    memory: memoryRef.optional(),
+    additionalPrompt: zod_1.z.string().optional(),
+    maxRetries: zod_1.z.number().int().positive().optional(),
+    timeoutMs: zod_1.z.number().int().positive().optional(),
+});
+exports.handoffTeamConfigSchema = zod_1.z.object({
+    agents: zod_1.z.array(agentRef).min(1),
+    edges: zod_1.z.array(exports.handoffEdgeSchema).min(1),
+    initialAgent: agentRef,
+    memory: memoryRef.optional(),
+    additionalPrompt: zod_1.z.string().optional(),
+    maxTransfers: zod_1.z.number().int().positive().optional(),
+    timeoutMs: zod_1.z.number().int().positive().optional(),
+    tokenBudget: zod_1.z.number().positive().optional(),
+    allowedTransitions: zod_1.z.record(zod_1.z.array(zod_1.z.string())).optional(),
+    onTransfer: zod_1.z.function().optional(),
+});
+exports.agentAsToolConfigSchema = zod_1.z.object({
+    agent: agentRef,
+    id: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    additionalPrompt: zod_1.z.string().optional(),
+    memory: exports.delegationMemorySchema.optional(),
+    inputSchema: zod_1.z.custom().optional(),
+});
+exports.hierarchicalTeamConfigSchema = zod_1.z.object({
+    manager: agentRef,
+    workers: zod_1.z.array(agentRef).min(1),
+    memory: memoryRef.optional(),
+    additionalPrompt: zod_1.z.string().optional(),
+    allowHandoff: zod_1.z.boolean().optional(),
+    workerCollaboration: zod_1.z.boolean().optional(),
+});
+exports.pipelineTeamConfigSchema = zod_1.z.object({
+    stages: zod_1.z.array(agentRef).min(1),
+    memory: memoryRef.optional(),
+    additionalPrompt: zod_1.z.string().optional(),
+});
+exports.committeeTeamConfigSchema = zod_1.z.object({
+    coordinator: agentRef,
+    members: zod_1.z.array(agentRef).min(1),
+    strategy: zod_1.z.enum(["vote", "summarize", "confidence", "first"]),
+    memory: memoryRef.optional(),
+    additionalPrompt: zod_1.z.string().optional(),
+    parallel: zod_1.z.boolean().optional(),
+});
+exports.aggregationStrategySchema = zod_1.z.enum([
+    "vote",
+    "summarize",
+    "confidence",
+    "first",
+]);

package/dist/multi-agent/utils/guardrails.d.ts

@@ -0,0 +1,6 @@
+export declare class GuardrailError extends Error {
+    constructor(message: string);
+}
+export declare function enforceMaxTransfers(current: number, max?: number): void;
+export declare function enforceAllowedTransition(from: string, to: string, allowed?: Record<string, string[]>): void;
+export declare function enforceTimeout<T>(promise: Promise<T>, timeoutMs?: number, label?: string): Promise<T>;

package/dist/multi-agent/utils/guardrails.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardrailError = void 0;
+exports.enforceMaxTransfers = enforceMaxTransfers;
+exports.enforceAllowedTransition = enforceAllowedTransition;
+exports.enforceTimeout = enforceTimeout;
+class GuardrailError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GuardrailError";
+    }
+}
+exports.GuardrailError = GuardrailError;
+function enforceMaxTransfers(current, max) {
+    if (max !== undefined && current >= max) {
+        throw new GuardrailError(`Max transfers exceeded (${max})`);
+    }
+}
+function enforceAllowedTransition(from, to, allowed) {
+    if (!allowed)
+        return;
+    const allowedTargets = allowed[from];
+    if (allowedTargets && !allowedTargets.includes(to)) {
+        throw new GuardrailError(`Transition from '${from}' to '${to}' is not allowed`);
+    }
+}
+function enforceTimeout(promise, timeoutMs, label = "operation") {
+    if (!timeoutMs)
+        return promise;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new GuardrailError(`${label} timed out after ${timeoutMs}ms`)), timeoutMs)),
+    ]);
+}

package/dist/multi-agent/utils/memory.d.ts

@@ -0,0 +1,8 @@
+import type { Agent } from "../../agent/Agent.js";
+import type { IMemory } from "../../agent/memory/index.js";
+import type { DelegationMemoryConfig } from "../types/index.js";
+export declare function overrideAgentMemory(agent: Agent, memory?: IMemory): () => void;
+export declare function resolveDelegationMemory(agent: Agent, config?: DelegationMemoryConfig, callingMemory?: IMemory): Promise<{
+    memory: IMemory;
+    restore: () => void;
+}>;

package/dist/multi-agent/utils/memory.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overrideAgentMemory = overrideAgentMemory;
+exports.resolveDelegationMemory = resolveDelegationMemory;
+const in_memory_js_1 = require("../../agent/memory/in-memory.js");
+function overrideAgentMemory(agent, memory) {
+    const original = agent.config.memory;
+    if (memory) {
+        agent.config.memory = memory;
+    }
+    return () => {
+        agent.config.memory = original;
+    };
+}
+async function resolveDelegationMemory(agent, config, callingMemory) {
+    const original = agent.config.memory;
+    if (!config) {
+        return { memory: original, restore: () => { } };
+    }
+    if (config.type === "shared") {
+        // Share calling history into the target's memory, without replacing it.
+        const memory = original;
+        if (callingMemory) {
+            const msgs = await callingMemory.getMessages();
+            for (const msg of msgs) {
+                await memory.addMessage(msg);
+            }
+        }
+        agent.config.memory = memory;
+        return { memory, restore: () => (agent.config.memory = original) };
+    }
+    if (config.type === "custom") {
+        agent.config.memory = config.memory;
+        return { memory: config.memory, restore: () => (agent.config.memory = original) };
+    }
+    // isolated
+    const isolated = new in_memory_js_1.InMemory();
+    agent.config.memory = isolated;
+    return { memory: isolated, restore: () => (agent.config.memory = original) };
+}

package/dist/multi-agent/utils/prompts.d.ts

@@ -0,0 +1,4 @@
+import type { Agent } from "../../agent/Agent.js";
+import type { AdditionalPrompt } from "../types/index.js";
+export declare function buildRouterSystemPrompt(agents: Agent[], additionalPrompt?: AdditionalPrompt): string;
+export declare function buildHandoffSystemPrompt(additionalPrompt?: AdditionalPrompt): string;

package/dist/multi-agent/utils/prompts.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRouterSystemPrompt = buildRouterSystemPrompt;
+exports.buildHandoffSystemPrompt = buildHandoffSystemPrompt;
+function buildRouterSystemPrompt(agents, additionalPrompt) {
+    const lines = agents.map((a) => `- ${a.name}: ${a.config?.instructions ?? a.name}`);
+    return [
+        "You are a routing controller.",
+        "Choose the best agent for the user request.",
+        "Respond ONLY with JSON: {\"agent\": \"<name>\"}.",
+        additionalPrompt ? `Guidance: ${additionalPrompt}` : "",
+        "Available agents:",
+        ...lines,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function buildHandoffSystemPrompt(additionalPrompt) {
+    return [
+        "You are coordinating handoffs between agents.",
+        additionalPrompt ? `Guidance: ${additionalPrompt}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/tracing/index.d.ts

@@ -0,0 +1,89 @@
+import type { ITelemetryExporter, TelemetrySpanKind, TelemetrySpanStatus } from "@nebulaos/types";
+export interface TracingContext {
+    /** W3C trace-id: 32 lowercase hex chars */
+    traceId: string;
+    /** W3C span-id: 16 lowercase hex chars */
+    spanId: string;
+    parentId?: string;
+}
+export interface SpanStartInput<K extends TelemetrySpanKind = TelemetrySpanKind> {
+    kind: K;
+    name: string;
+    data?: Record<string, unknown>;
+    correlationId?: string;
+    executionId?: string;
+}
+export interface SpanEndInput<K extends TelemetrySpanKind = TelemetrySpanKind> {
+    status: TelemetrySpanStatus;
+    data?: Record<string, unknown>;
+}
+/**
+ * Abstract tracing provider that can be injected into the core.
+ * The client package can supply an OpenTelemetry-backed implementation
+ * so that span IDs originate from OTel and the hierarchy is preserved
+ * end-to-end.
+ *
+ * The core has NO dependency on OpenTelemetry – only on this interface.
+ */
+export interface ITracingProvider {
+    /**
+     * Starts a new span and returns an ActiveSpan wrapper.
+     * The returned spanId MUST already be in W3C format (16 hex chars).
+     */
+    startSpan(input: SpanStartInput): ActiveSpan;
+    /**
+     * Returns the current trace context in W3C format, or undefined
+     * if there is no active span.
+     */
+    getContext(): TracingContext | undefined;
+    /**
+     * Runs a function within a new span context.
+     * The provider is responsible for context propagation (AsyncLocalStorage / OTel context).
+     */
+    withSpan<T>(input: SpanStartInput, fn: (span: ActiveSpan) => Promise<T>): Promise<T>;
+}
+export declare class ActiveSpan<K extends TelemetrySpanKind = TelemetrySpanKind> {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | undefined;
+    readonly kind: K;
+    readonly name: string;
+    private readonly correlationId;
+    private readonly executionId;
+    private readonly exporter;
+    private ended;
+    constructor(traceId: string, spanId: string, parentSpanId: string | undefined, kind: K, name: string, correlationId: string | undefined, executionId: string | undefined, exporter: ITelemetryExporter);
+    end(input: SpanEndInput<K>): Promise<void>;
+    get isEnded(): boolean;
+}
+export declare class Tracing {
+    private static exporter;
+    private static provider;
+    static setExporter(exporter: ITelemetryExporter): void;
+    /**
+     * 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: ITracingProvider): void;
+    /**
+     * Gets the current trace context.
+     * Returns undefined if called outside of a traced execution.
+     */
+    static getContext(): TracingContext | undefined;
+    /**
+     * Gets the current trace context or creates a dummy one if none exists.
+     * Useful for logging where you always want *some* ID.
+     */
+    static getContextOrDummy(): TracingContext;
+    /**
+     * 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 withSpan<T, K extends TelemetrySpanKind>(input: SpanStartInput<K>, fn: (span: ActiveSpan<K>) => Promise<T>): Promise<T>;
+    private static defaultWithSpan;
+}