@eggjs/agent-tracing 3.73.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/claude.d.ts

@@ -0,0 +1,2 @@
+export * from './index';
+export { ClaudeAgentTracer, TraceSession } from './src/ClaudeAgentTracer';

package/dist/claude.js

@@ -0,0 +1,22 @@
+"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 });
+exports.TraceSession = exports.ClaudeAgentTracer = void 0;
+__exportStar(require("./index"), exports);
+var ClaudeAgentTracer_1 = require("./src/ClaudeAgentTracer");
+Object.defineProperty(exports, "ClaudeAgentTracer", { enumerable: true, get: function () { return ClaudeAgentTracer_1.ClaudeAgentTracer; } });
+Object.defineProperty(exports, "TraceSession", { enumerable: true, get: function () { return ClaudeAgentTracer_1.TraceSession; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhdWRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vY2xhdWRlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBQUEsMENBQXdCO0FBQ3hCLDZEQUEwRTtBQUFqRSxzSEFBQSxpQkFBaUIsT0FBQTtBQUFFLGlIQUFBLFlBQVksT0FBQSJ9

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './src/types';
+export { AbstractOssClient } from './src/AbstractOssClient';
+export { AbstractLogServiceClient } from './src/AbstractLogServiceClient';

package/dist/index.js

@@ -0,0 +1,23 @@
+"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 });
+exports.AbstractLogServiceClient = exports.AbstractOssClient = void 0;
+__exportStar(require("./src/types"), exports);
+var AbstractOssClient_1 = require("./src/AbstractOssClient");
+Object.defineProperty(exports, "AbstractOssClient", { enumerable: true, get: function () { return AbstractOssClient_1.AbstractOssClient; } });
+var AbstractLogServiceClient_1 = require("./src/AbstractLogServiceClient");
+Object.defineProperty(exports, "AbstractLogServiceClient", { enumerable: true, get: function () { return AbstractLogServiceClient_1.AbstractLogServiceClient; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLDhDQUE0QjtBQUM1Qiw2REFBNEQ7QUFBbkQsc0hBQUEsaUJBQWlCLE9BQUE7QUFDMUIsMkVBQTBFO0FBQWpFLG9JQUFBLHdCQUF3QixPQUFBIn0=

package/dist/langgraph.d.ts

@@ -0,0 +1,2 @@
+export * from './index';
+export { LangGraphTracer } from './src/LangGraphTracer';

package/dist/langgraph.js

@@ -0,0 +1,21 @@
+"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 });
+exports.LangGraphTracer = void 0;
+__exportStar(require("./index"), exports);
+var LangGraphTracer_1 = require("./src/LangGraphTracer");
+Object.defineProperty(exports, "LangGraphTracer", { enumerable: true, get: function () { return LangGraphTracer_1.LangGraphTracer; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGFuZ2dyYXBoLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vbGFuZ2dyYXBoLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBQUEsMENBQXdCO0FBQ3hCLHlEQUF3RDtBQUEvQyxrSEFBQSxlQUFlLE9BQUEifQ==

package/dist/src/AbstractLogServiceClient.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Abstract log service client for dependency injection.
+ *
+ * To enable log service syncing in TracingService, implement this class in your application
+ * and register it with Tegg IoC. The implementation class MUST be named `LogServiceClient`
+ * (or use `@SingletonProto({ name: 'logServiceClient' })`) so the container can resolve it.
+ *
+ * @example
+ * ```typescript
+ * import { SingletonProto } from '@eggjs/core-decorator';
+ * import { AccessLevel } from '@eggjs/tegg-types';
+ * import { AbstractLogServiceClient } from '@eggjs/agent-tracing';
+ *
+ * // Class name must be LogServiceClient (registers as 'logServiceClient' in the IoC container)
+ * @SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+ * export class LogServiceClient extends AbstractLogServiceClient {
+ *   async send(log: string): Promise<void> {
+ *     await fetch('https://log.example.com/api', {
+ *       method: 'POST',
+ *       headers: { 'content-type': 'application/json' },
+ *       body: JSON.stringify({ log }),
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * If no implementation is registered, log service syncing is silently skipped.
+ */
+export declare abstract class AbstractLogServiceClient {
+    abstract send(log: string): Promise<void>;
+}

package/dist/src/AbstractLogServiceClient.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractLogServiceClient = void 0;
+/**
+ * Abstract log service client for dependency injection.
+ *
+ * To enable log service syncing in TracingService, implement this class in your application
+ * and register it with Tegg IoC. The implementation class MUST be named `LogServiceClient`
+ * (or use `@SingletonProto({ name: 'logServiceClient' })`) so the container can resolve it.
+ *
+ * @example
+ * ```typescript
+ * import { SingletonProto } from '@eggjs/core-decorator';
+ * import { AccessLevel } from '@eggjs/tegg-types';
+ * import { AbstractLogServiceClient } from '@eggjs/agent-tracing';
+ *
+ * // Class name must be LogServiceClient (registers as 'logServiceClient' in the IoC container)
+ * @SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+ * export class LogServiceClient extends AbstractLogServiceClient {
+ *   async send(log: string): Promise<void> {
+ *     await fetch('https://log.example.com/api', {
+ *       method: 'POST',
+ *       headers: { 'content-type': 'application/json' },
+ *       body: JSON.stringify({ log }),
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * If no implementation is registered, log service syncing is silently skipped.
+ */
+class AbstractLogServiceClient {
+}
+exports.AbstractLogServiceClient = AbstractLogServiceClient;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQWJzdHJhY3RMb2dTZXJ2aWNlQ2xpZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL0Fic3RyYWN0TG9nU2VydmljZUNsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBMkJHO0FBQ0gsTUFBc0Isd0JBQXdCO0NBRTdDO0FBRkQsNERBRUMifQ==

package/dist/src/AbstractOssClient.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Abstract OSS client for dependency injection.
+ *
+ * To enable OSS uploads in TracingService, implement this class in your application
+ * and register it with Tegg IoC. The implementation class MUST be named `OssClient`
+ * (or use `@SingletonProto({ name: 'ossClient' })`) so the container can resolve it.
+ *
+ * @example
+ * ```typescript
+ * import { SingletonProto } from '@eggjs/core-decorator';
+ * import { AccessLevel } from '@eggjs/tegg-types';
+ * import { AbstractOssClient } from '@eggjs/agent-tracing';
+ *
+ * // Class name must be OssClient (registers as 'ossClient' in the IoC container)
+ * @SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+ * export class OssClient extends AbstractOssClient {
+ *   async put(key: string, content: string | Buffer): Promise<void> {
+ *     // your OSS implementation here
+ *   }
+ * }
+ * ```
+ *
+ * If no implementation is registered, OSS uploads are silently skipped.
+ */
+export declare abstract class AbstractOssClient {
+    abstract put(key: string, content: string | Buffer): Promise<void>;
+}

package/dist/src/AbstractOssClient.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractOssClient = void 0;
+/**
+ * Abstract OSS client for dependency injection.
+ *
+ * To enable OSS uploads in TracingService, implement this class in your application
+ * and register it with Tegg IoC. The implementation class MUST be named `OssClient`
+ * (or use `@SingletonProto({ name: 'ossClient' })`) so the container can resolve it.
+ *
+ * @example
+ * ```typescript
+ * import { SingletonProto } from '@eggjs/core-decorator';
+ * import { AccessLevel } from '@eggjs/tegg-types';
+ * import { AbstractOssClient } from '@eggjs/agent-tracing';
+ *
+ * // Class name must be OssClient (registers as 'ossClient' in the IoC container)
+ * @SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+ * export class OssClient extends AbstractOssClient {
+ *   async put(key: string, content: string | Buffer): Promise<void> {
+ *     // your OSS implementation here
+ *   }
+ * }
+ * ```
+ *
+ * If no implementation is registered, OSS uploads are silently skipped.
+ */
+class AbstractOssClient {
+}
+exports.AbstractOssClient = AbstractOssClient;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQWJzdHJhY3RPc3NDbGllbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvQWJzdHJhY3RPc3NDbGllbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBdUJHO0FBQ0gsTUFBc0IsaUJBQWlCO0NBRXRDO0FBRkQsOENBRUMifQ==

package/dist/src/ClaudeAgentTracer.d.ts

@@ -0,0 +1,107 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { Logger } from '@eggjs/tegg-types';
+import type { Run } from '@langchain/core/tracers/base';
+import { type ClaudeMessage, type ClaudeContentBlock, type IRunCost, RunStatus, type TracerConfig } from './types';
+/**
+ * TraceSession - Manages state for a single agent execution with streaming support.
+ * Allows processing messages one-by-one and logging them immediately.
+ */
+export declare class TraceSession {
+    private traceId;
+    private rootRun;
+    private rootRunId;
+    private startTime;
+    private executionOrder;
+    private pendingToolUses;
+    private tracer;
+    constructor(tracer: ClaudeAgentTracer, sessionId?: string);
+    /**
+     * Process a single SDK message and log it immediately.
+     * Non-tracing message types (tool_progress, stream_event, status, etc.) are automatically ignored.
+     */
+    processMessage(message: SDKMessage): Promise<void>;
+    private handleInit;
+    private handleAssistant;
+    private handleUser;
+    private handleResult;
+    /**
+     * Get current trace ID
+     */
+    getTraceId(): string;
+}
+/**
+ * ClaudeAgentTracer - Converts Claude SDK messages to LangChain Run format
+ * and logs them to the same remote logging system as LangGraphTracer.
+ *
+ * Supports both batch processing (processMessages) and streaming (createSession).
+ */
+export declare class ClaudeAgentTracer {
+    /** @internal */
+    readonly logger: Logger;
+    private tracingService;
+    name: string;
+    agentName: string;
+    /**
+     * Configure the tracer with agent name and service credentials.
+     */
+    configure(config: TracerConfig): void;
+    /**
+     * Create a new trace session for streaming message processing.
+     * Use this for real-time tracing where messages arrive one-by-one.
+     *
+     * @example
+     * const session = claudeTracer.createSession();
+     * for await (const message of agent.run('task')) {
+     *   await session.processMessage(message);
+     * }
+     */
+    createSession(sessionId?: string): TraceSession;
+    /**
+     * Main entry point - convert SDK messages to Run trees and log them.
+     * Use this when you have all messages collected (batch processing).
+     * For real-time streaming, use createSession() instead.
+     *
+     * Non-tracing message types (tool_progress, stream_event, status, etc.) are automatically filtered out.
+     */
+    processMessages(sdkMessages: SDKMessage[]): Promise<void>;
+    /**
+     * @internal
+     * Convert an SDKMessage to internal ClaudeMessage format.
+     * Returns null for message types that are not relevant to tracing.
+     */
+    convertSDKMessage(msg: SDKMessage): ClaudeMessage | null;
+    /**
+     * @internal
+     * Create root run from init message (used by TraceSession)
+     */
+    createRootRunInternal(initMsg: ClaudeMessage, startTime: number, traceId: string, rootRunId?: string): Run;
+    /**
+     * @internal
+     * Create LLM run from assistant message (used by TraceSession)
+     */
+    createLLMRunInternal(msg: ClaudeMessage, rootRunId: string, traceId: string, order: number, startTime: number, isToolCall: boolean): Run;
+    /**
+     * @internal
+     * Create tool run at start (before result, used by TraceSession)
+     */
+    createToolRunStartInternal(toolUseBlock: ClaudeContentBlock, rootRunId: string, traceId: string, order: number, startTime: number): Run;
+    /**
+     * @internal
+     * Complete tool run with result (used by TraceSession)
+     */
+    completeToolRunInternal(toolRun: Run, toolResultBlock: ClaudeContentBlock, startTime: number): void;
+    /**
+     * Extract token usage from Claude SDK usage object into IRunCost format.
+     */
+    private extractTokenUsage;
+    /**
+     * @internal
+     * Create run cost from result message (used by TraceSession)
+     */
+    createRunCostInternal(resultMsg: ClaudeMessage): IRunCost;
+    /**
+     * @internal
+     * Log trace - delegates to TracingService (used by TraceSession)
+     */
+    logTrace(run: Run, status: RunStatus): void;
+}