@a5c-ai/agent-mux-observability 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Common types and interfaces for agent-mux observability.
+ */
+/**
+ * Log levels supported by the system.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Cost information structure for tracking LLM usage.
+ */
+export interface CostInfo {
+    totalUsd?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    thinkingTokens?: number;
+}
+/**
+ * Contextual information that can be attached to log entries.
+ */
+export interface LogContext {
+    /** Run ID for correlating logs across a single run */
+    runId?: string;
+    /** Agent name being used */
+    agent?: string;
+    /** Session ID for multi-turn conversations */
+    sessionId?: string;
+    /** Model being used */
+    model?: string;
+    /** User ID or identifier */
+    userId?: string;
+    /** Request/operation ID for tracing */
+    operationId?: string;
+    /** Component or module name */
+    component?: string;
+    /** Duration in milliseconds for performance tracking */
+    duration?: number;
+    /** Cost information */
+    cost?: CostInfo;
+    /** Error information */
+    error?: {
+        code?: string;
+        message?: string;
+        stack?: string;
+        recoverable?: boolean;
+        name?: string;
+    };
+    /** Additional arbitrary metadata */
+    [key: string]: unknown;
+}
+/**
+ * Logger interface for agent-mux.
+ */
+export interface Logger {
+    level: string;
+    trace(msg: string): void;
+    trace(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    debug(obj: object, msg?: string): void;
+    info(msg: string): void;
+    info(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    error(msg: string): void;
+    error(obj: object, msg?: string): void;
+    fatal(msg: string): void;
+    fatal(obj: object, msg?: string): void;
+    /** Create a child logger with additional context */
+    child(bindings: LogContext): Logger;
+    /** Log agent run start */
+    runStart(context: {
+        runId: string;
+        agent: string;
+        prompt: string;
+        model?: string;
+    }): void;
+    /** Log agent run completion */
+    runComplete(context: {
+        runId: string;
+        agent: string;
+        duration: number;
+        cost?: CostInfo;
+    }): void;
+    /** Log agent run error */
+    runError(context: {
+        runId: string;
+        agent: string;
+        error: Error | LogContext['error'];
+    }): void;
+    /** Log tool call start */
+    toolCallStart(context: {
+        runId: string;
+        toolName: string;
+        toolCallId: string;
+        args?: unknown;
+    }): void;
+    /** Log tool call completion */
+    toolCallComplete(context: {
+        runId: string;
+        toolName: string;
+        toolCallId: string;
+        duration: number;
+        result?: unknown;
+    }): void;
+    /** Log session events */
+    session(message: string, context: LogContext & {
+        action?: 'create' | 'resume' | 'fork' | 'end';
+    }): void;
+    perf?(message: string, context: LogContext & {
+        duration: number;
+    }): void;
+    auth?(message: string, context: LogContext & {
+        method?: string;
+        success?: boolean;
+    }): void;
+    config?(message: string, context: LogContext): void;
+}
+/**
+ * Telemetry interface for agent-mux.
+ */
+export interface Telemetry {
+    /** Record agent run start */
+    recordRunStart(agent: string, model?: string): void;
+    /** Record agent run completion */
+    recordRunComplete(agent: string, model: string | undefined, duration: number, cost?: CostInfo): void;
+    /** Record agent run error */
+    recordRunError(agent: string, model: string | undefined, error: Error | string, cost?: CostInfo): void;
+    /** Record tool call */
+    recordToolCall(toolName: string, duration: number, success: boolean): void;
+    /** Record authentication event */
+    recordAuthEvent(agent: string, method: string, success: boolean): void;
+    /** Start tracing an agent run */
+    startRunSpan(runId: string, agent: string, model?: string): any;
+    /** Start tracing a tool call */
+    startToolCallSpan(toolName: string, toolCallId: string, parentSpan?: any): any;
+    /** Start tracing a subagent delegation */
+    startSubagentSpan(subagentId: string, agentName: string, parentSpan?: any): any;
+    /** End a span with success */
+    endSpanSuccess(span: any, attributes?: Record<string, string | number | boolean>): void;
+    /** End a span with error */
+    endSpanError(span: any, error: Error | string, attributes?: Record<string, string | number | boolean>): void;
+    /** Initialize telemetry */
+    initialize?(): void;
+    /** Shutdown telemetry */
+    shutdown?(): Promise<void>;
+    /** Set active runs gauge */
+    setActiveRuns?(count: number): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Common types and interfaces for agent-mux observability.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@a5c-ai/agent-mux-observability",
+  "version": "0.4.0",
+  "description": "Logging and telemetry infrastructure for agent-mux",
+  "keywords": ["logging", "telemetry", "observability", "opentelemetry", "pino"],
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/"],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist/",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/semantic-conventions": "^1.29.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "vitest": "^4.1.4"
+  }
+}