@inkeep/agents-sdk 0.39.4 → 0.40.0

package/dist/telemetry-provider.d.ts

@@ -0,0 +1,218 @@
+//#region src/telemetry-provider.d.ts
+/**
+ * TelemetryProvider - Abstraction for Telemetry/Observability
+ *
+ * This module provides a clean abstraction over telemetry implementations.
+ * Cloud customers can use this without needing to install or configure
+ * OpenTelemetry or Signoz directly.
+ *
+ * Telemetry is OPT-IN - if not configured, a no-op provider is used.
+ *
+ * @example
+ * ```typescript
+ * // Opt-in to telemetry with default console logger
+ * import { InkeepTelemetryProvider, createConsoleTelemetryProvider } from '@inkeep/agents-sdk'
+ *
+ * const telemetry = createConsoleTelemetryProvider()
+ *
+ * // Or with OpenTelemetry (requires @opentelemetry packages)
+ * const telemetry = createOpenTelemetryProvider({
+ *   serviceName: 'my-agent',
+ *   endpoint: 'http://localhost:4318'
+ * })
+ * ```
+ */
+/**
+ * Span status codes
+ */
+declare const SpanStatus: {
+  readonly OK: "ok";
+  readonly ERROR: "error";
+  readonly UNSET: "unset";
+};
+type SpanStatusType = (typeof SpanStatus)[keyof typeof SpanStatus];
+/**
+ * Span interface for tracing
+ */
+interface TelemetrySpan {
+  /** Set span attributes */
+  setAttributes(attributes: Record<string, unknown>): TelemetrySpan;
+  /** Set a single attribute */
+  setAttribute(key: string, value: unknown): TelemetrySpan;
+  /** Record an exception */
+  recordException(error: Error): TelemetrySpan;
+  /** Set span status */
+  setStatus(status: SpanStatusType, message?: string): TelemetrySpan;
+  /** Add an event to the span */
+  addEvent(name: string, attributes?: Record<string, unknown>): TelemetrySpan;
+  /** End the span */
+  end(): void;
+  /** Check if span is recording */
+  isRecording(): boolean;
+  /** Update span name */
+  updateName(name: string): TelemetrySpan;
+}
+/**
+ * Span options
+ */
+interface SpanOptions {
+  /** Span attributes */
+  attributes?: Record<string, unknown>;
+  /** Parent span (for context propagation) */
+  parent?: TelemetrySpan;
+}
+/**
+ * Tracer interface for creating spans
+ */
+interface TelemetryTracer {
+  /** Start a new active span and execute callback */
+  startActiveSpan<T>(name: string, fn: (span: TelemetrySpan) => T): T;
+  startActiveSpan<T>(name: string, options: SpanOptions, fn: (span: TelemetrySpan) => T): T;
+  /** Start a new span without making it active */
+  startSpan(name: string, options?: SpanOptions): TelemetrySpan;
+}
+/**
+ * Logger interface for structured logging
+ */
+interface TelemetryLogger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Metrics interface for recording measurements
+ */
+interface TelemetryMetrics {
+  /** Increment a counter */
+  increment(name: string, value?: number, attributes?: Record<string, unknown>): void;
+  /** Record a gauge value */
+  gauge(name: string, value: number, attributes?: Record<string, unknown>): void;
+  /** Record a histogram value */
+  histogram(name: string, value: number, attributes?: Record<string, unknown>): void;
+}
+/**
+ * Main telemetry provider interface
+ */
+interface TelemetryProvider {
+  /** Get a tracer for creating spans */
+  getTracer(name: string, version?: string): TelemetryTracer;
+  /** Get a logger for structured logging */
+  getLogger(name: string): TelemetryLogger;
+  /** Get metrics for recording measurements */
+  getMetrics(name: string): TelemetryMetrics;
+  /** Shutdown the telemetry provider */
+  shutdown(): Promise<void>;
+  /** Check if telemetry is enabled */
+  isEnabled(): boolean;
+}
+/**
+ * Configuration for telemetry provider
+ */
+interface TelemetryConfig {
+  /** Whether telemetry is enabled (default: false) */
+  enabled?: boolean;
+  /** Service name for identifying the source */
+  serviceName?: string;
+  /** Service version */
+  serviceVersion?: string;
+  /** Custom provider implementation */
+  provider?: TelemetryProvider;
+}
+/**
+ * No-op telemetry provider (default)
+ */
+declare class NoOpTelemetryProvider implements TelemetryProvider {
+  getTracer(_name: string, _version?: string): TelemetryTracer;
+  getLogger(_name: string): TelemetryLogger;
+  getMetrics(_name: string): TelemetryMetrics;
+  shutdown(): Promise<void>;
+  isEnabled(): boolean;
+}
+/**
+ * Console-based telemetry provider for development/debugging
+ */
+declare class ConsoleTelemetryProvider implements TelemetryProvider {
+  private serviceName;
+  constructor(serviceName?: string);
+  getTracer(name: string, _version?: string): TelemetryTracer;
+  getLogger(name: string): TelemetryLogger;
+  getMetrics(name: string): TelemetryMetrics;
+  shutdown(): Promise<void>;
+  isEnabled(): boolean;
+}
+/**
+ * InkeepTelemetryProvider - Main telemetry management class
+ *
+ * Provides a unified interface for telemetry across the SDK.
+ * Telemetry is OPT-IN - by default, a no-op provider is used.
+ */
+declare class InkeepTelemetryProvider {
+  private provider;
+  constructor(config?: TelemetryConfig);
+  /**
+   * Get a tracer for creating spans
+   */
+  getTracer(name: string, version?: string): TelemetryTracer;
+  /**
+   * Get a logger for structured logging
+   */
+  getLogger(name: string): TelemetryLogger;
+  /**
+   * Get metrics recorder
+   */
+  getMetrics(name: string): TelemetryMetrics;
+  /**
+   * Check if telemetry is enabled
+   */
+  isEnabled(): boolean;
+  /**
+   * Shutdown the provider
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Get the underlying provider
+   */
+  getProvider(): TelemetryProvider;
+  /**
+   * Set as the global telemetry provider
+   */
+  setAsGlobal(): void;
+}
+/**
+ * Get the global telemetry provider
+ */
+declare function getGlobalTelemetryProvider(): TelemetryProvider;
+/**
+ * Set the global telemetry provider
+ */
+declare function setGlobalTelemetryProvider(provider: TelemetryProvider): void;
+/**
+ * Create a no-op telemetry provider (default, does nothing)
+ */
+declare function createNoOpTelemetryProvider(): InkeepTelemetryProvider;
+/**
+ * Create a console-based telemetry provider for development
+ */
+declare function createConsoleTelemetryProvider(serviceName?: string): InkeepTelemetryProvider;
+/**
+ * Configuration for OpenTelemetry provider
+ */
+interface OpenTelemetryConfig {
+  /** Service name */
+  serviceName: string;
+  /** Service version */
+  serviceVersion?: string;
+  /** OTLP endpoint URL */
+  endpoint?: string;
+  /** Additional resource attributes */
+  resourceAttributes?: Record<string, string>;
+}
+/**
+ * Create an OpenTelemetry-based provider
+ *
+ * Note: Requires @opentelemetry packages to be installed
+ */
+declare function createOpenTelemetryProvider(config: OpenTelemetryConfig): Promise<InkeepTelemetryProvider>;
+//#endregion
+export { ConsoleTelemetryProvider, InkeepTelemetryProvider, NoOpTelemetryProvider, OpenTelemetryConfig, SpanOptions, SpanStatus, SpanStatusType, TelemetryConfig, TelemetryLogger, TelemetryMetrics, TelemetryProvider, TelemetrySpan, TelemetryTracer, createConsoleTelemetryProvider, createNoOpTelemetryProvider, createOpenTelemetryProvider, getGlobalTelemetryProvider, setGlobalTelemetryProvider };

package/dist/telemetry-provider.js

@@ -0,0 +1,390 @@
+import { __require } from "./_virtual/rolldown_runtime.js";
+
+//#region src/telemetry-provider.ts
+/**
+* TelemetryProvider - Abstraction for Telemetry/Observability
+*
+* This module provides a clean abstraction over telemetry implementations.
+* Cloud customers can use this without needing to install or configure
+* OpenTelemetry or Signoz directly.
+*
+* Telemetry is OPT-IN - if not configured, a no-op provider is used.
+*
+* @example
+* ```typescript
+* // Opt-in to telemetry with default console logger
+* import { InkeepTelemetryProvider, createConsoleTelemetryProvider } from '@inkeep/agents-sdk'
+*
+* const telemetry = createConsoleTelemetryProvider()
+*
+* // Or with OpenTelemetry (requires @opentelemetry packages)
+* const telemetry = createOpenTelemetryProvider({
+*   serviceName: 'my-agent',
+*   endpoint: 'http://localhost:4318'
+* })
+* ```
+*/
+/**
+* Span status codes
+*/
+const SpanStatus = {
+	OK: "ok",
+	ERROR: "error",
+	UNSET: "unset"
+};
+/**
+* No-op span implementation
+*/
+const createNoOpSpan = () => ({
+	setAttributes: function() {
+		return this;
+	},
+	setAttribute: function() {
+		return this;
+	},
+	recordException: function() {
+		return this;
+	},
+	setStatus: function() {
+		return this;
+	},
+	addEvent: function() {
+		return this;
+	},
+	end: () => {},
+	isRecording: () => false,
+	updateName: function() {
+		return this;
+	}
+});
+/**
+* No-op tracer implementation
+*/
+const createNoOpTracer = () => ({
+	startActiveSpan(_name, arg1, arg2) {
+		const fn = typeof arg1 === "function" ? arg1 : arg2;
+		if (!fn) throw new Error("No callback function provided");
+		return fn(createNoOpSpan());
+	},
+	startSpan(_name, _options) {
+		return createNoOpSpan();
+	}
+});
+/**
+* No-op logger implementation
+*/
+const createNoOpLogger = () => ({
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+});
+/**
+* No-op metrics implementation
+*/
+const createNoOpMetrics = () => ({
+	increment: () => {},
+	gauge: () => {},
+	histogram: () => {}
+});
+/**
+* No-op telemetry provider (default)
+*/
+var NoOpTelemetryProvider = class {
+	getTracer(_name, _version) {
+		return createNoOpTracer();
+	}
+	getLogger(_name) {
+		return createNoOpLogger();
+	}
+	getMetrics(_name) {
+		return createNoOpMetrics();
+	}
+	async shutdown() {}
+	isEnabled() {
+		return false;
+	}
+};
+/**
+* Console-based telemetry provider for development/debugging
+*/
+var ConsoleTelemetryProvider = class {
+	serviceName;
+	constructor(serviceName = "inkeep-agent") {
+		this.serviceName = serviceName;
+	}
+	getTracer(name, _version) {
+		const serviceName = this.serviceName;
+		const createConsoleSpan = (spanName) => {
+			const startTime = Date.now();
+			const attributes = {};
+			const events = [];
+			return {
+				setAttributes: function(attrs) {
+					Object.assign(attributes, attrs);
+					return this;
+				},
+				setAttribute: function(key, value) {
+					attributes[key] = value;
+					return this;
+				},
+				recordException: function(error) {
+					console.error(`[${serviceName}:${name}] Exception in ${spanName}:`, error.message);
+					return this;
+				},
+				setStatus: function(status, message) {
+					if (status === SpanStatus.ERROR) console.error(`[${serviceName}:${name}] ${spanName} ERROR:`, message);
+					return this;
+				},
+				addEvent: function(eventName, eventAttrs) {
+					events.push({
+						name: eventName,
+						attributes: eventAttrs
+					});
+					return this;
+				},
+				end: () => {
+					const duration = Date.now() - startTime;
+					console.log(`[${serviceName}:${name}] ${spanName} completed in ${duration}ms`, {
+						attributes,
+						events
+					});
+				},
+				isRecording: () => true,
+				updateName: function(newName) {
+					console.log(`[${serviceName}:${name}] Span renamed: ${spanName} -> ${newName}`);
+					return this;
+				}
+			};
+		};
+		return {
+			startActiveSpan(spanName, arg1, arg2) {
+				const fn = typeof arg1 === "function" ? arg1 : arg2;
+				if (!fn) throw new Error("No callback function provided");
+				const span = createConsoleSpan(spanName);
+				try {
+					return fn(span);
+				} finally {
+					span.end();
+				}
+			},
+			startSpan(spanName, _options) {
+				return createConsoleSpan(spanName);
+			}
+		};
+	}
+	getLogger(name) {
+		const prefix = `[${this.serviceName}:${name}]`;
+		return {
+			debug: (message, context) => console.debug(prefix, message, context),
+			info: (message, context) => console.info(prefix, message, context),
+			warn: (message, context) => console.warn(prefix, message, context),
+			error: (message, context) => console.error(prefix, message, context)
+		};
+	}
+	getMetrics(name) {
+		const prefix = `[${this.serviceName}:${name}]`;
+		return {
+			increment: (metricName, value = 1, attributes) => console.log(`${prefix} COUNTER ${metricName}: +${value}`, attributes),
+			gauge: (metricName, value, attributes) => console.log(`${prefix} GAUGE ${metricName}: ${value}`, attributes),
+			histogram: (metricName, value, attributes) => console.log(`${prefix} HISTOGRAM ${metricName}: ${value}`, attributes)
+		};
+	}
+	async shutdown() {
+		console.log(`[${this.serviceName}] Telemetry provider shutting down`);
+	}
+	isEnabled() {
+		return true;
+	}
+};
+let globalProvider = new NoOpTelemetryProvider();
+/**
+* InkeepTelemetryProvider - Main telemetry management class
+*
+* Provides a unified interface for telemetry across the SDK.
+* Telemetry is OPT-IN - by default, a no-op provider is used.
+*/
+var InkeepTelemetryProvider = class {
+	provider;
+	constructor(config = {}) {
+		if (config.provider) this.provider = config.provider;
+		else if (config.enabled) this.provider = new ConsoleTelemetryProvider(config.serviceName);
+		else this.provider = new NoOpTelemetryProvider();
+	}
+	/**
+	* Get a tracer for creating spans
+	*/
+	getTracer(name, version) {
+		return this.provider.getTracer(name, version);
+	}
+	/**
+	* Get a logger for structured logging
+	*/
+	getLogger(name) {
+		return this.provider.getLogger(name);
+	}
+	/**
+	* Get metrics recorder
+	*/
+	getMetrics(name) {
+		return this.provider.getMetrics(name);
+	}
+	/**
+	* Check if telemetry is enabled
+	*/
+	isEnabled() {
+		return this.provider.isEnabled();
+	}
+	/**
+	* Shutdown the provider
+	*/
+	async shutdown() {
+		return this.provider.shutdown();
+	}
+	/**
+	* Get the underlying provider
+	*/
+	getProvider() {
+		return this.provider;
+	}
+	/**
+	* Set as the global telemetry provider
+	*/
+	setAsGlobal() {
+		globalProvider = this.provider;
+	}
+};
+/**
+* Get the global telemetry provider
+*/
+function getGlobalTelemetryProvider() {
+	return globalProvider;
+}
+/**
+* Set the global telemetry provider
+*/
+function setGlobalTelemetryProvider(provider) {
+	globalProvider = provider;
+}
+/**
+* Create a no-op telemetry provider (default, does nothing)
+*/
+function createNoOpTelemetryProvider() {
+	return new InkeepTelemetryProvider({ enabled: false });
+}
+/**
+* Create a console-based telemetry provider for development
+*/
+function createConsoleTelemetryProvider(serviceName) {
+	return new InkeepTelemetryProvider({
+		enabled: true,
+		serviceName,
+		provider: new ConsoleTelemetryProvider(serviceName)
+	});
+}
+/**
+* Wrap an OpenTelemetry span in our TelemetrySpan interface
+*/
+function wrapOtelSpan(otelSpan) {
+	return {
+		setAttributes: function(attributes) {
+			otelSpan.setAttributes(attributes);
+			return this;
+		},
+		setAttribute: function(key, value) {
+			otelSpan.setAttribute(key, value);
+			return this;
+		},
+		recordException: function(error) {
+			otelSpan.recordException(error);
+			return this;
+		},
+		setStatus: function(status, message) {
+			const statusCode = status === SpanStatus.ERROR ? 2 : status === SpanStatus.OK ? 1 : 0;
+			otelSpan.setStatus({
+				code: statusCode,
+				message
+			});
+			return this;
+		},
+		addEvent: function(name, attributes) {
+			otelSpan.addEvent(name, attributes);
+			return this;
+		},
+		end: () => otelSpan.end(),
+		isRecording: () => otelSpan.isRecording(),
+		updateName: function(name) {
+			otelSpan.updateName(name);
+			return this;
+		}
+	};
+}
+/**
+* Check if OpenTelemetry is available
+*/
+function isOpenTelemetryAvailable() {
+	try {
+		/** @lintignore Skip report as unlisted dependencies by Knip */
+		__require.resolve("@opentelemetry/api");
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Load OpenTelemetry module dynamically
+*/
+async function loadOpenTelemetryModule() {
+	return new Function("specifier", "return import(specifier)")("@opentelemetry/api");
+}
+/**
+* Create an OpenTelemetry-based provider
+*
+* Note: Requires @opentelemetry packages to be installed
+*/
+async function createOpenTelemetryProvider(config) {
+	if (!isOpenTelemetryAvailable()) {
+		console.warn("OpenTelemetry packages not installed. Install with: npm install @opentelemetry/api @opentelemetry/sdk-node");
+		return createNoOpTelemetryProvider();
+	}
+	try {
+		const { trace } = await loadOpenTelemetryModule();
+		return new InkeepTelemetryProvider({
+			enabled: true,
+			provider: {
+				getTracer(name, version) {
+					const otelTracer = trace.getTracer(name, version);
+					return {
+						startActiveSpan(spanName, arg1, arg2) {
+							const fn = typeof arg1 === "function" ? arg1 : arg2;
+							const options = typeof arg1 === "object" ? arg1 : void 0;
+							if (!fn) throw new Error("No callback function provided");
+							return otelTracer.startActiveSpan(spanName, options?.attributes ? { attributes: options.attributes } : {}, (otelSpan) => {
+								return fn(wrapOtelSpan(otelSpan));
+							});
+						},
+						startSpan(spanName, options) {
+							return wrapOtelSpan(otelTracer.startSpan(spanName, options?.attributes ? { attributes: options.attributes } : {}));
+						}
+					};
+				},
+				getLogger(name) {
+					return new ConsoleTelemetryProvider(config.serviceName).getLogger(name);
+				},
+				getMetrics(_name) {
+					return createNoOpMetrics();
+				},
+				async shutdown() {},
+				isEnabled() {
+					return true;
+				}
+			}
+		});
+	} catch (error) {
+		console.warn("Failed to initialize OpenTelemetry:", error instanceof Error ? error.message : "Unknown error");
+		return createNoOpTelemetryProvider();
+	}
+}
+
+//#endregion
+export { ConsoleTelemetryProvider, InkeepTelemetryProvider, NoOpTelemetryProvider, SpanStatus, createConsoleTelemetryProvider, createNoOpTelemetryProvider, createOpenTelemetryProvider, getGlobalTelemetryProvider, setGlobalTelemetryProvider };

package/dist/tool.d.ts

@@ -0,0 +1,53 @@
+import { AgentMcpConfig, AgentMcpConfigInput } from "./builders.js";
+import { MCPToolConfig } from "@inkeep/agents-core";
+
+//#region src/tool.d.ts
+interface ToolInterface {
+  config: MCPToolConfig;
+  init(): Promise<void>;
+  getId(): string;
+  getName(): string;
+  getDescription(): string;
+  getServerUrl(): string;
+  getActiveTools(): string[] | undefined;
+  getCredentialReferenceId(): string | null | undefined;
+  with(config: AgentMcpConfigInput): AgentMcpConfig;
+}
+declare class Tool implements ToolInterface {
+  config: MCPToolConfig;
+  private baseURL;
+  private tenantId;
+  private initialized;
+  private projectId;
+  constructor(config: Omit<MCPToolConfig, 'tenantId' | 'projectId'>);
+  setContext(tenantId: string, projectId: string, baseURL?: string): void;
+  getId(): string;
+  getName(): string;
+  getDescription(): string;
+  getServerUrl(): string;
+  getActiveTools(): string[] | undefined;
+  getCredentialReferenceId(): string | null | undefined;
+  init(options?: {
+    skipDatabaseRegistration?: boolean;
+  }): Promise<void>;
+  private upsertTool;
+  /**
+   * Creates a new AgentMcpConfig with the given configuration.
+   *
+   * @param config - The configuration for the AgentMcpConfig
+   * @returns A new AgentMcpConfig
+   *
+   * example:
+   * ```typescript
+   * const tool = new Tool({
+   *   id: 'tool-id',
+   *   name: 'Tool Name',
+   *   serverUrl: 'https://example.com/mcp',
+   * });
+   * const agentMcpConfig = tool.with({ selectedTools: ['tool-1', 'tool-2'], headers: { 'Authorization': 'Bearer token' } });
+   * ```
+   */
+  with(config: AgentMcpConfigInput): AgentMcpConfig;
+}
+//#endregion
+export { Tool, ToolInterface };