@ai-setting/roy-agent-cli 1.3.14 → 1.3.16

package/dist/core/src/env/log-trace/opentelemetry/propagation-env.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Propagation Env Module
+ *
+ * 提供便捷的环境变量注入功能，用于在子进程执行时传递 trace context。
+ *
+ * @example
+ * ```typescript
+ * import { injectToEnv, injectToEnvWithContext } from "./propagation-env.js";
+ *
+ * // 在 Bash 工具中执行子进程前：
+ * const traceEnv = injectToEnv();  // 从当前 OTelTracerProvider 获取并注入
+ * const options = {
+ *   env: { ...process.env, ...traceEnv, ...env },
+ * };
+ * spawn(command, args, options);
+ * ```
+ */
+import { propagation } from "./propagation.js";
+import { getTracerProvider } from "./tracer-provider.js";
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * 从当前 OTelTracerProvider 获取上下文并注入到环境变量
+ *
+ * 这是一个便捷函数，封装了常见的注入模式：
+ * 1. 从全局 TracerProvider 获取当前 Tracer
+ * 2. 获取当前 span context
+ * 3. 注入到目标环境变量
+ *
+ * @param env 目标环境变量对象（默认：{}）
+ * @returns 注入了 TRACEPARENT 的环境变量对象
+ *
+ * @example
+ * ```typescript
+ * const env = injectToEnv({ PATH: '/usr/bin' });
+ * // env.TRACEPARENT = '00-{traceId}-{spanId}-01'
+ * // env.PATH = '/usr/bin'
+ * ```
+ */
+export function injectToEnv(env = {}) {
+    const provider = getTracerProvider();
+    // 如果 provider 未初始化，尝试获取 tracer（可能会自动初始化）
+    const tracer = provider.getTracer('roy-tracer');
+    tracer.injectToEnv(env);
+    return env;
+}
+/**
+ * 将指定的 SpanContext 直接注入到环境变量
+ *
+ * 与 injectToEnv 不同，这个函数不需要访问全局 TracerProvider，
+ * 直接使用传入的 SpanContext 进行注入。
+ *
+ * @param env 目标环境变量对象
+ * @param context 要注入的 SpanContext
+ * @returns 注入了 TRACEPARENT 的环境变量对象
+ *
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan('my-span');
+ * const env = injectToEnvWithContext({}, span.spanContext);
+ * ```
+ */
+export function injectToEnvWithContext(env, context) {
+    propagation.inject(env, context);
+    return env;
+}
+/**
+ * 从源环境变量 carrier 复制 TRACEPARENT 到目标 carrier
+ *
+ * 用于将一个环境变量对象中的 trace context 传递到另一个：
+ * - 从 process.env 复制到子进程的环境变量
+ * - 从父进程环境变量复制到子进程环境变量
+ *
+ * @param target 目标 carrier（将被修改）
+ * @param source 源 carrier
+ * @returns 目标 carrier
+ *
+ * @example
+ * ```typescript
+ * // 在 fork 子进程时继承父进程的 trace context
+ * const childEnv = injectToEnvFromCarrier({}, process.env);
+ * ```
+ */
+export function injectToEnvFromCarrier(target, source) {
+    const extracted = propagation.extract(source);
+    if (extracted) {
+        // 将提取的上下文重新注入到目标
+        // ExtractedContext 包含发送方的 traceId 和 spanId
+        // 需要构造新的 SpanContext 用于传播
+        const context = {
+            traceId: extracted.traceId,
+            spanId: extracted.spanId, // 使用发送方的 spanId
+            parentSpanId: undefined, // 新的 span 将作为根 span（但会继承 traceId）
+        };
+        propagation.inject(target, context);
+    }
+    return target;
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * 获取 TRACEPARENT 字段名
+ */
+export function getTraceparentHeader() {
+    return propagation.getTraceparentHeader();
+}
+//# sourceMappingURL=propagation-env.js.map

package/dist/core/src/env/log-trace/opentelemetry/propagation-env.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Propagation Env 测试
+ *
+ * 测试 propagation-env 模块：
+ * - injectToEnv: 从当前 OTelTracerProvider 获取上下文并注入环境变量
+ * - injectToEnvWithContext: 直接注入指定 SpanContext
+ */
+export {};
+//# sourceMappingURL=propagation-env.test.d.ts.map

package/dist/core/src/env/log-trace/opentelemetry/propagation-env.test.js

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Propagation Env 测试
+ *
+ * 测试 propagation-env 模块：
+ * - injectToEnv: 从当前 OTelTracerProvider 获取上下文并注入环境变量
+ * - injectToEnvWithContext: 直接注入指定 SpanContext
+ */
+import { describe, test, expect, beforeEach, vi } from 'bun:test';
+import { injectToEnv, injectToEnvWithContext, injectToEnvFromCarrier, } from "./propagation-env.js";
+import { propagation } from "./propagation.js";
+// Mock the tracer-provider module
+const mockInjectToEnv = vi.fn();
+const mockGetCurrentContext = vi.fn();
+vi.mock('./tracer-provider', () => ({
+    getTracerProvider: vi.fn().mockReturnValue({
+        getTracer: vi.fn().mockReturnValue({
+            injectToEnv: mockInjectToEnv,
+            getCurrentContext: mockGetCurrentContext,
+        }),
+        isInitialized: vi.fn().mockReturnValue(true),
+    }),
+}));
+describe('propagation-env', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('injectToEnv', () => {
+        test('should inject TRACEPARENT to provided env object', async () => {
+            // Create a mock tracer with current context
+            const mockSpanContext = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            mockGetCurrentContext.mockReturnValue(mockSpanContext);
+            mockInjectToEnv.mockImplementation((env) => {
+                env['TRACEPARENT'] = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+            });
+            const env = {};
+            injectToEnv(env);
+            expect(env['TRACEPARENT']).toBeDefined();
+            expect(env['TRACEPARENT']).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/);
+        });
+        test('should not inject if no current context', () => {
+            mockGetCurrentContext.mockReturnValue(undefined);
+            mockInjectToEnv.mockImplementation((_env) => { });
+            const env = {};
+            injectToEnv(env);
+            // injectToEnv should not set TRACEPARENT when no context
+            expect(mockInjectToEnv).toHaveBeenCalledWith(env);
+        });
+        test('should preserve existing env variables', () => {
+            const mockSpanContext = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            mockGetCurrentContext.mockReturnValue(mockSpanContext);
+            mockInjectToEnv.mockImplementation((env) => {
+                env['TRACEPARENT'] = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+            });
+            const env = {
+                HOME: '/home/user',
+                PATH: '/usr/bin',
+                CUSTOM_VAR: 'custom-value',
+            };
+            injectToEnv(env);
+            expect(env['HOME']).toBe('/home/user');
+            expect(env['PATH']).toBe('/usr/bin');
+            expect(env['CUSTOM_VAR']).toBe('custom-value');
+            expect(env['TRACEPARENT']).toBeDefined();
+        });
+    });
+    describe('injectToEnvWithContext', () => {
+        test('should inject given SpanContext to env', () => {
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: 'a1b2c3d4e5f67890',
+            };
+            const env = {};
+            injectToEnvWithContext(env, context);
+            // 验证 propagation.inject 被正确调用
+            expect(env['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should inject traceparent format correctly', () => {
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            const env = {};
+            injectToEnvWithContext(env, context);
+            const traceparent = env['TRACEPARENT'];
+            expect(traceparent).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should overwrite existing TRACEPARENT', () => {
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            const env = {
+                TRACEPARENT: '00-old-trace-old-span-old-flags',
+            };
+            injectToEnvWithContext(env, context);
+            expect(env['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+    });
+    describe('injectToEnvFromCarrier', () => {
+        test('should inject from source carrier to target carrier', () => {
+            const sourceCarrier = {
+                TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+            };
+            const targetCarrier = {};
+            injectToEnvFromCarrier(targetCarrier, sourceCarrier);
+            expect(targetCarrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should return undefined if source has no TRACEPARENT', () => {
+            const sourceCarrier = {};
+            const targetCarrier = {};
+            injectToEnvFromCarrier(targetCarrier, sourceCarrier);
+            expect(targetCarrier['TRACEPARENT']).toBeUndefined();
+        });
+    });
+});
+describe('propagation-env integration', () => {
+    test('should produce valid W3C traceparent format', () => {
+        const context = {
+            traceId: '0af7651916cd43dd8448eb211c80319c',
+            spanId: 'b7ad6b7169203331',
+            parentSpanId: undefined,
+        };
+        const env = {};
+        injectToEnvWithContext(env, context);
+        // Parse and verify format
+        const parsed = propagation.extract(env);
+        expect(parsed).toBeDefined();
+        expect(parsed.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+        expect(parsed.spanId).toBe('b7ad6b7169203331');
+    });
+});
+//# sourceMappingURL=propagation-env.test.js.map

package/dist/core/src/env/log-trace/opentelemetry/propagation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview W3C TraceContext Propagation
+ *
+ * 实现 W3C Trace Context 标准中的 traceparent 格式：
+ * https://www.w3.org/TR/trace-context/#traceparent-header
+ *
+ * 格式: 00-{traceId}-{parentSpanId}-{flags}
+ * - version: 2字符，固定 "00"
+ * - traceId: 32字符，128位追踪ID
+ * - parentSpanId: 16字符，64位父Span ID
+ * - flags: 2字符，采样标志（当前固定 "01"）
+ */
+import type { SpanContext } from "../types";
+/**
+ * 将 SpanContext 序列化为 traceparent 字符串
+ *
+ * W3C TraceContext 语义：
+ * - traceparent 中的 spanId 是"发送方 span"的 ID
+ * - 接收方会将其作为新 span 的 parentSpanId
+ * - 所以应该使用 context.spanId，而非 parentSpanId
+ *
+ * @param context SpanContext
+ * @returns traceparent 格式字符串
+ */
+export declare function serialize(context: SpanContext): string;
+/**
+ * 提取的 Trace Context
+ *
+ * W3C TraceContext 格式: 00-{traceId}-{spanId}-{flags}
+ * - {spanId} 是发送方 span 的 ID
+ * - 接收方应将其作为新 span 的 parentSpanId
+ */
+export interface ExtractedContext {
+    traceId: string;
+    /** 发送方 span 的 ID，接收方应作为新 span 的 parentSpanId */
+    spanId: string;
+}
+/**
+ * 将 traceparent 字符串反序列化为 ExtractedContext
+ *
+ * W3C TraceContext 语义：
+ * - traceparent 中的 "span-id" 是发送方 span 的 ID
+ * - 接收方应该：
+ *   - 使用提取的 traceId
+ *   - 将提取的 spanId 作为 parentSpanId
+ *   - 生成自己的新 spanId
+ *
+ * @param traceparent traceparent 格式字符串
+ * @returns 接收方 ExtractedContext 或 undefined（格式无效）
+ */
+export declare function parse(traceparent: string): ExtractedContext | undefined;
+/**
+ * W3C TraceContext Propagation 实现
+ *
+ * 用于在进程间传递 trace 上下文：
+ * - inject: 将 SpanContext 注入到 carrier（环境变量）
+ * - extract: 从 carrier（环境变量）提取 SpanContext
+ */
+export declare const propagation: {
+    /**
+     * 将 SpanContext 注入到 carrier
+     *
+     * @param carrier 载体对象（通常是环境变量对象）
+     * @param context Span 上下文
+     */
+    inject(carrier: Record<string, string | undefined>, context: SpanContext): void;
+    /**
+     * 从 carrier 提取 SpanContext
+     *
+     * @param carrier 载体对象（通常是环境变量对象）
+     * @returns ExtractedContext 或 undefined
+     */
+    extract(carrier: Record<string, string | undefined>): ExtractedContext | undefined;
+    /**
+     * 获取 traceparent 字段名
+     */
+    getTraceparentHeader(): string;
+};
+export type { SpanContext } from "../types";
+//# sourceMappingURL=propagation.d.ts.map

package/dist/core/src/env/log-trace/opentelemetry/propagation.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview W3C TraceContext Propagation
+ *
+ * 实现 W3C Trace Context 标准中的 traceparent 格式：
+ * https://www.w3.org/TR/trace-context/#traceparent-header
+ *
+ * 格式: 00-{traceId}-{parentSpanId}-{flags}
+ * - version: 2字符，固定 "00"
+ * - traceId: 32字符，128位追踪ID
+ * - parentSpanId: 16字符，64位父Span ID
+ * - flags: 2字符，采样标志（当前固定 "01"）
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** W3C TraceContext 版本号 */
+const TRACE_CONTEXT_VERSION = "00";
+/** 采样标志（01 = sampled） */
+const TRACE_FLAGS_SAMPLED = "01";
+/** traceparent 字段名 */
+const TRACEPARENT_HEADER = "TRACEPARENT";
+/** 版本号长度 */
+const VERSION_LENGTH = 2;
+/** traceId 长度 */
+const TRACE_ID_LENGTH = 32;
+/** parentSpanId 长度 */
+const PARENT_SPAN_ID_LENGTH = 16;
+/** flags 长度 */
+const FLAGS_LENGTH = 2;
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * 左补零到指定长度
+ */
+function padLeft(str, length) {
+    return str.padStart(length, "0");
+}
+/**
+ * 验证是否为有效的十六进制字符串
+ */
+function isValidHex(str) {
+    return /^[0-9a-f]+$/i.test(str);
+}
+// ============================================================================
+// Serialization (SpanContext -> traceparent)
+// ============================================================================
+/**
+ * 将 SpanContext 序列化为 traceparent 字符串
+ *
+ * W3C TraceContext 语义：
+ * - traceparent 中的 spanId 是"发送方 span"的 ID
+ * - 接收方会将其作为新 span 的 parentSpanId
+ * - 所以应该使用 context.spanId，而非 parentSpanId
+ *
+ * @param context SpanContext
+ * @returns traceparent 格式字符串
+ */
+export function serialize(context) {
+    const traceId = padLeft(context.traceId.toLowerCase(), TRACE_ID_LENGTH);
+    const spanId = padLeft(context.spanId.toLowerCase(), PARENT_SPAN_ID_LENGTH);
+    // 格式: 00-{traceId}-{spanId}-{flags}
+    // 注意：使用 spanId 而非 parentSpanId，因为这是发送方 span 的 ID
+    const parts = [
+        TRACE_CONTEXT_VERSION,
+        traceId,
+        spanId,
+        TRACE_FLAGS_SAMPLED,
+    ];
+    return parts.join("-");
+}
+/**
+ * 将 traceparent 字符串反序列化为 ExtractedContext
+ *
+ * W3C TraceContext 语义：
+ * - traceparent 中的 "span-id" 是发送方 span 的 ID
+ * - 接收方应该：
+ *   - 使用提取的 traceId
+ *   - 将提取的 spanId 作为 parentSpanId
+ *   - 生成自己的新 spanId
+ *
+ * @param traceparent traceparent 格式字符串
+ * @returns 接收方 ExtractedContext 或 undefined（格式无效）
+ */
+export function parse(traceparent) {
+    if (!traceparent || typeof traceparent !== "string") {
+        return undefined;
+    }
+    const trimmed = traceparent.trim();
+    const parts = trimmed.split("-");
+    // 必须有 4 个部分
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    const [version, traceId, senderSpanId, flags] = parts;
+    // 验证版本（当前只支持 "00"）
+    if (version !== TRACE_CONTEXT_VERSION) {
+        // 未来版本兼容：对于 "ff" 及以上的未来版本，忽略
+        if (version > TRACE_CONTEXT_VERSION) {
+            return undefined;
+        }
+    }
+    // 验证 traceId 长度和格式
+    if (traceId.length !== TRACE_ID_LENGTH || !isValidHex(traceId)) {
+        return undefined;
+    }
+    // 验证 spanId 长度和格式（W3C 标准中叫 span-id，但这是发送方 span 的 ID）
+    if (senderSpanId.length !== PARENT_SPAN_ID_LENGTH || !isValidHex(senderSpanId)) {
+        return undefined;
+    }
+    // 验证 flags 长度（当前忽略 flags 值，只验证格式）
+    if (flags.length !== FLAGS_LENGTH || !isValidHex(flags)) {
+        return undefined;
+    }
+    // 返回提取的上下文
+    // - traceId: 保持不变
+    // - spanId: 发送方 span 的 ID（接收方应作为新 span 的 parentSpanId）
+    return {
+        traceId: traceId.toLowerCase(),
+        spanId: senderSpanId.toLowerCase(),
+    };
+}
+// ============================================================================
+// Propagation Interface
+// ============================================================================
+/**
+ * W3C TraceContext Propagation 实现
+ *
+ * 用于在进程间传递 trace 上下文：
+ * - inject: 将 SpanContext 注入到 carrier（环境变量）
+ * - extract: 从 carrier（环境变量）提取 SpanContext
+ */
+export const propagation = {
+    /**
+     * 将 SpanContext 注入到 carrier
+     *
+     * @param carrier 载体对象（通常是环境变量对象）
+     * @param context Span 上下文
+     */
+    inject(carrier, context) {
+        carrier[TRACEPARENT_HEADER] = serialize(context);
+    },
+    /**
+     * 从 carrier 提取 SpanContext
+     *
+     * @param carrier 载体对象（通常是环境变量对象）
+     * @returns ExtractedContext 或 undefined
+     */
+    extract(carrier) {
+        const traceparent = carrier[TRACEPARENT_HEADER];
+        if (!traceparent) {
+            return undefined;
+        }
+        return parse(traceparent);
+    },
+    /**
+     * 获取 traceparent 字段名
+     */
+    getTraceparentHeader() {
+        return TRACEPARENT_HEADER;
+    },
+};
+//# sourceMappingURL=propagation.js.map

package/dist/core/src/env/log-trace/opentelemetry/propagation.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview W3C TraceContext Propagation 测试
+ *
+ * 测试 W3C TraceContext 标准的 traceparent 格式：
+ * - 注入 (inject): 将 SpanContext 序列化到环境变量
+ * - 提取 (extract): 从环境变量反序列化 SpanContext
+ * - 序列化 (serialize): SpanContext -> traceparent 字符串
+ * - 反序列化 (parse): traceparent 字符串 -> SpanContext
+ */
+export {};
+//# sourceMappingURL=propagation.test.d.ts.map