import { TraceSource } from '../types/agent';
import { TRACE_TYPES, TRACE_STATUS } from '../constants';

/**
 * Represents a single step within a trace (e.g., an LLM call or a tool execution).
 */
export interface TraceStep {
  /** Unique identifier for the step. */
  stepId: string;
  /** The type of event being recorded. */
  type: (typeof TRACE_TYPES)[keyof typeof TRACE_TYPES];
  /** The content of the step (e.g., LLM prompts, tool results). */
  content: unknown;
  /** Timestamp (Unix epoch) of the step. */
  timestamp: number;
  /** Optional metadata associated with the step. */
  metadata?: Record<string, unknown>;
}

/**
 * Full record of an agent's reasoning trace node.
 */
export interface Trace {
  /** Unique identifier for the trace. */
  traceId: string;
  /** Unique identifier for this specific node in the trace graph. */
  nodeId: string;
  /** Unique identifier for the parent node that spawned this one. */
  parentId?: string;
  /** The ID of the user or session the trace belongs to. */
  userId: string;
  /** Optional workspace ID for multi-tenant isolation. */
  workspaceId?: string;
  /** The origin of the request (e.g., 'dashboard', 'telegram', 'system'). */
  source: TraceSource | string;
  /** The ID of the agent executing this trace node. */
  agentId?: string;
  /** Start timestamp of the trace. */
  timestamp: number;
  /** Current status of the trace. */
  status: (typeof TRACE_STATUS)[keyof typeof TRACE_STATUS] | string;
  /** Initial context provided when the trace was started. */
  initialContext: Record<string, unknown>;
  /** Sequential list of steps performed during the trace. */
  steps: TraceStep[];
  /** Expiration timestamp for DynamoDB TTL. */
  expiresAt: number;
  /** Final textual response generated by the agent. */
  finalResponse?: string;
  /** Reason for failure if status is FAILED. */
  failureReason?: string;
  /** End timestamp of the trace. */
  endTime?: number;
  /** Additional metadata for the trace. */
  metadata?: Record<string, unknown>;
}
